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Abstract 


This document provides sockets Application Program Interface (API) to 
support "advanced" IPv6 applications, as a supplement to a separate 
specification, RFC 3493. The expected applications include Ping, 
Traceroute, routing daemons and the like, which typically use raw 
sockets to access IPv6 or ICMPv6 header fields. This document 
proposes some portable interfaces for applications that use raw 
sockets under IPv6. There are other features of IPv6 that some 
applications will need to access: interface identification 
(specifying the outgoing interface and determining the incoming 
interface), IPv6 extension headers, and path Maximum Transmission 
Unit (MTU) information. This document provides API access to these 
features too. Additionally, some extended interfaces to libraries 
for the "r" commands are defined. The extension will provide better 
backward compatibility to existing implementations that are not 
IPv6-capable. 
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1. Introduction 


A separate specification [RFC-3493] contains changes to the sockets 
API to support IP version 6. Those changes are for TCP and UDP-based 
applications. This document defines some of the "advanced" features 
of the sockets API that are required for applications to take 
advantage of additional features of IPv6. 
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Today, the portability of applications using IPv4 raw sockets is 
quite high, but this is mainly because most IPv4 implementations 
started from a common base (the Berkeley source code) or at least 
started with the Berkeley header files. This allows programs such as 
Ping and Traceroute, for example, to compile with minimal effort on 
many hosts that support the sockets API. With IPv6, however, there 
is no common source code base that implementors are starting from, 
and the possibility for divergence at this level between different 
implementations is high. To avoid a complete lack of portability 
amongst applications that use raw IPv6 sockets, some standardization 
is necessary. 


There are also features from the basic IPv6 specification that are 
not addressed in [RFC-3493]: sending and receiving Routing headers, 
Hop-by-Hop options, and Destination options, specifying the outgoing 
interface, being told of the receiving interface, and control of path 
MTU information. 


This document updates and replaces RFC 2292. This revision is based 
on implementation experience of RFC 2292, as well as some additional 
extensions that have been found to be useful through the IPv6 
deployment. Note, however, that further work on this document may 
still be needed. Once the API specification becomes mature and is 
deployed among implementations, it may be formally standardized by a 
more appropriate body, such as has been done with the Basic API 
[RFC-3493]. 


This document can be divided into the following main sections. 


1. Definitions of the basic constants and structures required for 
applications to use raw IPv6 sockets. This includes structure 
definitions for the IPv6 and ICMPv6 headers and all associated 
constants (e.g., values for the Next Header field). 


2. Some basic semantic definitions for IPv6 raw sockets. For 
example, a raw ICMPv4 socket requires the application to calculate 
and store the ICMPv4 header checksum. But with IPv6 this would 
require the application to choose the source IPv6 address because 
the source address is part of the pseudo header that ICMPv6 now 
uses for its checksum computation. It should be defined that with 
a raw ICMPv6 socket the kernel always calculates and stores the 
ICMPv6 header checksum. 


3. Packet information: how applications can obtain the received 
interface, destination address, and received hop limit, along with 
specifying these values on a per-packet basis. There are a class 
of applications that need this capability and the technique should 
be portable. 
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4. Access to the optional Routing header, Hop-by-Hop options, and 
Destination options extension headers. 


5. Additional features required for improved IPv6 application 
portability. 


The packet information along with access to the extension headers 
(Routing header, Hop-by-Hop options, and Destination options) are 
specified using the "ancillary data" fields that were added to the 
4.3BSD Reno sockets API in 1990. The reason is that these ancillary 
data fields are part of the Posix standard [POSIX] and should 
therefore be adopted by most vendors. 


This document does not address application access to either the 
authentication header or the encapsulating security payload header. 


Many examples in this document omit error checking in favor of 
brevity and clarity. 


We note that some of the functions and socket options defined in this 
document may have error returns that are not defined in this 
document. Some of these possible error returns will be recognized 
only as implementations proceed. 


Datatypes in this document follow the Posix format: intN t means a 
signed integer of exactly N bits (e.g., intl6 t) and uintN t means an 
unsigned integer of exactly N bits (e.g., uint32 t). 


Note that we use the (unofficial) terminology ICMPv4, IGMPv4, and 
ARPv4 to avoid any confusion with the newer ICMPv6 protocol. 


2. Common Structures and Definitions 


Many advanced applications examine fields in the IPv6 header and set 
and examine fields in the various ICMPv6 headers. Common structure 
definitions for these protocol headers are required, along with 
common constant definitions for the structure members. 


This API assumes that the fields in the protocol headers are left in 
the network byte order, which is big-endian for the Internet 


protocols. If not, then either these constants or the fields being 
tested must be converted at run-time, using something like htons() or 
htonl(). 


Two new header files are defined: <netinet/ip6.h> and 
<netinet/icmp6.h>. 
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When an include file is specified, that include file is allowed to 
include other files that do the actual declaration or definition. 


2.1. The ip6 hdr Structure 


The following structure is defined as a result of including 
<netinet/ip6.h>. Note that this is a new header. 


struct ip6 hdr { 
union ( 
struct ip6_hdrctl ( 
uint32_t ip6_unl_flow; /* 4 bits version, 8 bits TC, 20 bits 


flow-ID */ 
uint16 t ip6_unl_plen; /* payload length */ 
uint8_t ip6_unl_nxt; /* next header */ 
uint8 t ip6_unl_hlim; /* hop limit */ 
} ip6 unl; 
uint8 t ip6 un2 vfc; /* 4 bits version, top 4 bits 


tclass */ 
} ip6 ctlun; 
struct in6_addr ip6_src; /* source address */ 
struct in6_addr ip6_dst; /* destination address */ 
}; 


#define ip6_vfc ip6 ctlun.ip6 un2 vfc 

#define ip6 flow dip6 ctlun.ip6 unl.ip6 unl flow 
#define ip6 plen ip6 ctlun.ip6 unl.ip6 unl plen 
#define ip6 nxt ip6 ctlun.ip6 unl.ip6 unl nxt 
#define ip6 hlim ip6_ctlun.ip6_unl.ip6_unl_hlim 
#define ip6 hops dip6 ctlun.ip6 unl.ip6 unl hlim 


Ds, IPv6 Next Header Values 


IPv6 defines many new values for the Next Header field. The 
following constants are defined as a result of including 
<netinet/in.h>. 


#define IPPROTO HOPOPTS 0 /* IPv6 Hop-by-Hop options */ 
#define IPPROTO IPV6 41 /* IPv6 header */ 

#define IPPROTO ROUTING 43 /* IPv6 Routing header */ 
#define IPPROTO FRAGMENT 44 /* IPv6 fragment header */ 


#define IPPROTO ESP 50 /* encapsulating security payload */ 
#define IPPROTO AH 51 /* authentication header */ 

#define IPPROTO ICMPV6 58 /* ICMPv6 */ 

#define IPPROTO NONE 59 /* IPv6 no next header */ 


#define IPPROTO DSTOPTS 60 /* IPv6 Destination options */ 
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Berkeley-derived IPv4 implementations also define IPPROTO IP to be 0. 
This should not be a problem since IPPROTO IP is used only with IPv4 
sockets and IPPROTO HOPOPTS only with IPv6 sockets. 


2.1.2. IPv6 Extension Headers 


Six extension headers are defined for IPv6. We define structures for 
all except the Authentication header and Encapsulating Security 
Payload header, both of which are beyond the scope of this document. 
The following structures are defined as a result of including 
<netinet/ip6.h>. 


/* Hop-by-Hop options header */ 
struct ip6_hbh { 
uint8 t ip6h nxt; /* next header */ 
uint8 t ip6h len; /* length in units of 8 octets */ 
/* followed by options */ 
}; 


/* Destination options header */ 
struct ip6_dest { 
uint8 t ip6d_nxt; /* next header */ 
uint8 t ip6d len; /* length in units of 8 octets */ 
/* followed by options */ 
}; 


/* Routing header */ 
struct ip6 rthdr { 


uint8 七 ip6r_nxt; /* next header */ 

uint8 t ip6r len; /* length in units of 8 octets */ 
uint8 t ipé6r type; /* routing type */ 

uint8 t ip6r_segleft; /* segments left */ 


/* followed by routing type specific data */ 
}; 


/* Type 0 Routing header */ 
struct ip6 rthdrO { 


uint8 七 ip6r0 nxt; /* next header */ 

uint8 t ip6r0 len; /* length in units of 8 octets */ 
uint8 t ip6r0 type; /* always zero */ 

uint8 t ip6r0 segleft; /* segments left */ 

uint32 t ip6r0 reserved; /* reserved field */ 


/* followed by up to 127 struct in6 addr */ 
}; 
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/* Fragment header */ 
struct ip6_frag { 


uint8_t ip6f_nxt; /* next header */ 
uint8 t ip6f reserved; /* reserved field */ 
uintl6 t ip6f offlg; /* offset, reserved, and flag */ 
uint32 t ip6f_ident; /* identification */ 
}; 
#if BYTE ORDER == BIG ENDIAN 
#define IP6F OFF MASK Oxfff8 /* mask out offset from 


ip6f offlg */ 
#define IP6F RESERVED MASK 0x0006 /* reserved bits in 
ip6f offlg */ 


#define IP6F MORE FRAG 0x0001 /* more-fragments flag */ 
#else /* BYTE_ORDER == LITTLE_ENDIAN */ 
#define IP6F_OFF_MASK Oxf8ff /* mask out offset from 


ip6f_offlg */ 

#define IP6F_RESERVED_MASK 0x0600 /* reserved bits in 
ip6f_offlg */ 

#define IP6F_MORE_FRAG 0x0100 /* more-fragments flag */ 
fendif 


2.1.3.  IPv6 Options 


Several options are defined for IPv6, and we define structures and 
macro definitions for some of them below. The following structures 
are defined as a result of including <netinet/ip6.h>. 


/* IPv6 options */ 
struct ip6_opt { 
uint8_t ip60 type; 
uint8 t ip60 len; 
}; 


Fk 

* The high-order 3 bits of the option type define the behavior 

* when processing an unknown option and whether or not the option 
* content changes in flight. 


*/ 
#define IP6OPT TYPE(o) ((0) & OxcO) 
#define IP6OPT TYPE SKIP 0x00 


#define IP6OPT TYPE DISCARD 0x40 
#define IP6OPT TYPE FORCEICMP 0x80 


#define IP6OPT TYPE ICMP 0xc0 
#define IP6OPT MUTABLE 0x20 
#define IP6OPT PAD1 0x00 /* 00 0 00000 */ 
#define IP6OPT PADN 0x01 /* 00 0 00001 */ 
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#define IP6O0PT JUMBO Oxc2 /* 11 0 00010 */ 
#define IP60PT_NSAP_ADDR Oxc3 /* 11 0 00011 */ 
#define IP60PT_TUNNEL_LIMIT 0x04 /* 00 0 00100 */ 
#define IP60PT_ROUTER_ALERT 0x05 /* 00 0 00101 */ 


/* Jumbo Payload Option */ 
struct ip6_opt_jumbo { 

uint8 t ip60j type; 

uint8 t ip60j len; 

uint8 t ip60j jumbo len[41; 
}; 
#define IP6OPT JUMBO LEN 6 


/* NSAP Address Option */ 
struct ip6 opt nsap { 
uint8 t ip6on type; 
uint8 t ip6on_ len; 
uint8 t ip6on src nsap len; 
uint8 t ip6on dst nsap len; 
/* followed by source NSAP */ 
/* followed by destination NSAP */ 
}; 


/* Tunnel Limit Option */ 
struct ip6 opt tunnel { 
uint8 t ip6o0t type; 
uint8 t ip60t len; 
uint8 七 ip60t encap limit; 
}; 


/* Router Alert Option */ 
struct ip6 opt router { 
uint8 t ip6or type; 
uint8 t ipé6or len; 
uint8 t ip6or_value[2]; 
}; 


/* Router alert values (in network byte order) */ 
#ifdef _BIG ENDIAN 


#define IP6 ALERT MLD 0x0000 
#define IP6 ALERT RSVP 0x0001 
#define IP6_ALERT_AN 0x0002 
#else 

#define IP6 ALERT MLD 0x0000 
#define IP6 ALERT RSVP 0x0100 
#define IP6 ALERT AN 0x0200 
#endif 
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2.2. The icmpé6 hdr Structure 

The ICMPv6 header is needed by numerous IPv6 applications including 
Ping, Traceroute, router discovery daemons, and neighbor discovery 
daemons. The following structure is defined as a result of including 
<netinet/icmp6.h>. Note that this is a new header. 


struct icmp6_hdr { 


uint8_t icmp6 type; /* type field */ 

uint8 七 icmp6 code; /* code field */ 

uintl6 t icmp6 cksum; /* checksum field */ 

union ( 
uint32 七 icmp6 un data32[l]; /* type-specific field */ 
uintl6 七 icmp6 un datal6[2]; /* type-specific field */ 
uint8 t icmpé6 un data8[4]; /* type-specific field */ 


) icmp6 dataun; 
}; 


#define icmp6_data32 icmp6_dataun.icmp6_un_data32 

#define icmp6 datal6 icmp6 dataun.icmpé6 un datal6 

#define icmp6 data8 icmp6 dataun.icmpé6 un data8 

#define icmp6 pptr icmp6 data32[0] /* parameter prob */ 
#define icmp6 mtu icmpé6 data32[0] /* packet too big */ 
#define icmp6 id icmp6 datal6[0] /* echo request/reply */ 
#define icmp6_seq icmp6_datal6[1] /* echo request/reply */ 


#define 


icmp6_maxdelay 


icmpé6 datal6[0] 


/* 


mcast group 


membership */ 


2.2.1. ICMPv6 Type and Code Values 

In addition to a common structure for the ICMPv6 header, common 
definitions are required for the ICMPv6 type and code fields. 
following constants are also defined as a result of including 
<netinet/icmp6.h>. 


The 


#define 
#define 
#define 
#define 


ICMP 6_DST_UNREACH 
ICMP 6_PACKET_TOO_BIG 
ICMP6 TIME EXCEEDED 
ICMP6 PARAM PROB 


RUNKE 


0x80 /* all informational 


messages */ 


#define ICMP6 INFOMSG MASK 


128 
129 


#define 
#define 


ICMP 6_ECHO_REQUEST 
ICMP6 ECHO REPLY 


/* no route to 
destination */ 


#define ICMP6 DST UNREACH NOROUTE 0 
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#define 


#define 


#define 
#define 


#define 


#define 


#define 


#define 


#define 


The five ICMP message types defined by IPv6 neighbor discovery 
are defined in the next section. 


137) 


AREA 
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ICMP6 DST UNREACH ADMIN 


ICMP6 DST UNREACH BEYONDSCOPE 2 


ICMP6 DST UNREACH ADDR 
ICMP6 DST UNREACH NOPORT 


ICMP6 TIME EXCEED TRANSIT 


ICMP6 TIME EXCEED REASSEMBLY 1 


ICMP6 PARAMPROB HEADER 0 /* 
ICMP6 PARAMPROB NEXTHEADER Tx 
ICMP6_PARAMPROB_OPTION PARTA 


ICMPv6 Neighbor Discovery Definitions 


IPv6 
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communication with 
destination */ 

admin. prohibited */ 
beyond scope of source 
address */ 

address unreachable */ 
bad port */ 


Hop Limit == 0 in 
transit */ 
Reassembly time out */ 


erroneous header 
field */ 
unrecognized 
Next Header */ 
unrecognized 
IPv6 option */ 


(133- 


The following structures and definitions are defined as a result of 
including <netinet/icmp6.h>. 


#define 
#define 
#define 
#define 
#define 


struct nd_router_solicit { 
struct icmp6_hdr 


ND_ROUTER_SOLICIT 
ND_ROUTER_ADVERT 
ND_NEIGHBOR_SOLICIT 
ND_NEIGHBOR_ADVERT 
ND_REDIRECT 


nd rs hdr; 


1:33 
134 
135 
136 
137 


/* could be followed by options */ 


}; 


#define 
#define 
#define 
#define 


Stevens, 
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nd rs type 

nd rs code 

nd rs cksum 

nd rs reserved 


nd rs hdr 
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/* router solicitation */ 


.icmp6 type 
nd rs hdr. 
nd rs hdr. 
nd rs hdr. 


icmp6 code 
icmp6_cksum 
icmp6 data32[0] 
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struct nd router advert ( 
struct icmp6 hdr mnd ra hdr; 
uint32 t nd ra reachable; 
uint32 t nd ra retransmit; 
/* could be followed by options */ 


/* reachabl 


}; 


#define nd ra type nd ra hdr. 
#define nd ra code nd ra hdr. 
#define nd ra cksum nd ra hdr. 
#define nd ra curhoplimit nd ra hdr. 
#define nd ra flags reserved nd ra hdr. 
#define ND RA FLAG MANAGED 0x80 

#define ND RA FLAG OTHER 0x40 

#define nd_ra_router_lifetime nd_ra_hdr. 


struct nd_neighbor_solicit { /* neighbor 

struct icmp6_hdr nd_ns_hdr; 

struct in6_addr nd_ns_target; /* target 
/* could be followed by options */ 


}; 


#define nd ns type nd ns hdr. 
#define nd ns code nd ns hdr. 
#define nd ns cksum nd ns hadr. 
#define nd ns reserved nd ns hdr. 


struct nd neighbor advert ( /* neighbor 

struct icmp6 hdr mnd na hdr; 

struct in6 addr nd na target; /* target 
/* could be followed by options */ 


}; 


#define nd na type nd na hdr. 
#define nd na code nd na hdr. 
#define nd na cksum nd na hdr. 
#define nd na flags reserved nd na hdr. 


#if BYTE ORDER == BIG ENDIAN 
#define ND NA FLAG ROUTER 0x80000000 
#define ND NA FLAG SOLICITED 0x40000000 
#define ND NA FLAG OVERRIDE 0x20000000 
#else /* BYTE ORDER == LITTLE ENDIAN */ 
#define ND NA FLAG ROUTER 0x00000080 
#define ND NA FLAG SOLICITED 0x00000040 
#define ND NA FLAG OVERRIDE 0x00000020 
tendif 
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/* router advertisement */ 


e time */ 


/* retransmit timer */ 


icmp6 type 
icmp6 code 
icmp6_cksum 
icmp6_data8[0] 
icmp6_data8[1] 


icmp6 datal6[1] 


solicitation */ 


address */ 


icmp6 type 
icmp6 code 
icmp6_cksum 
icmp6_data32[0] 


advertisement */ 


address */ 


icmp6_type 
icmp6_code 
icmp6_cksum 
icmp6_data32[0] 
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struct nd redirect ( 
struct icmp6 hdr 
struct in6 addr 
struct in6 addr 
/* could be followed by options */ 


}; 


#define nd rd type 
#define nd rd code 


#define nd rd cksum 
#define nd rd reserved 


struct nd opt hdr { 
nd opt type; 
nd opt len; 


uint8 t 
uint8 t 


/* redirect */ 


nd rd hdr; 
nd rd target; /* target address */ 


nd rd dst; 


nd rd hdr.icmp6 type 
nd rd hdr.icmpé6 code 
nd rd hdr.icmpé6 cksum 


May 2003 


/* destination address */ 


nd rd hdr.icmpé6 data32[0] 


/* Neighbor discovery option header */ 


/* in units of 8 octets */ 


/* followed by option specific data */ 


}; 


#define ND OPT SOURCE LINKADDR 
#define ND OPT TARGET LINKADDR 
#define ND OPT PREFIX INFORMATION 
#define ND OPT REDIRECTED HEADER 
#define ND OPT MTU 


struct nd opt prefix info ( 


RUNE 


flags reserved; 


valid time; 


preferred time; 


uint8 七 nd opt pi type; 

uint8 t nd opt pi len; 

uint8 t nd opt pi prefix len; 
uint8 t nd opt pi 

uint32 t nd opt pi 

uint32 t nd opt pi 

uint32 t nd opt pi reserved2; 


struct in6 addr 


}; 


nd opt pi prefix; 


#define ND OPT PI FLAG ONLINK 0x80 
#define ND OPT PI FLAG AUTO 0x40 


struct nd opt rd hdr ( 


uint8 t 
uint8 t 
uintl6 t 


/* redirected header */ 


nd opt rh type; 
nd opt rh len; 
nd opt rh reservedl; 


uint32 t 


nd opt rh reserved2; 


/* followed by IP header and data */ 


}; 
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struct nd opt mtu ( /* MTU option */ 
uint8 t nd opt mtu type; 
uint8 t nd opt mtu len; 
uintl6 t nd opt mtu reserved; 
uint32 t nd opt mtu mtu; 
}; 


We note that the nd na flags reserved flags have the same byte 
ordering problems as we showed with ip6f offlg. 


2.2.3. Multicast Listener Discovery Definitions 


The following structures and definitions are defined as a result of 
including <netinet/icmp6.h>. 


#define MLD LISTENER QUERY 130 
#define MLD LISTENER REPORT 131 
#define MLD LISTENER REDUCTION 132 


struct mld hdr { 

struct icmp6 hdr mld icmp6 hdr; 

struct in6 addr mld addr; /* multicast address */ 
}; 


#define mld_type mld_icmp6_hdr.icmp6_type 
#define mld_code mld_icmp6_hdr.icmp6_code 
#define mld_cksum mld_icmp6_hdr.icmp6_cksum 
#define mld_maxdelay mld icmp6 hdr.icmp6 datal6[0] 
#define mld reserved mld icmp6 hdr.icmp6 datal6[l] 


2.2.4. ICMPv6 Router Renumbering Definitions 


The following structures and definitions are defined as a result of 
including <netinet/icmp6.h>. 


#define ICMP6_ROUTER_RENUMBERING 138 /* router renumbering */ 


struct icmp6_router_renum { /* router renumbering header */ 
struct icmp6é_hdr rr hdr; 


uint8 t rr segnum; 

uint8 t rr flags; 

uintl6 t rr maxdelay; 

uint32 t rr reserved; 
}; 
#define rr type rr hdr.icmpé6 type 
#define rr code rr hdr.icmp6 code 
#define rr cksum rr hdr.icmp6 cksum 
#define rr_seqnum rr_hdr.icmp6_data32[0] 
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/* Router renumbering flags */ 
#define ICMP6 RR FLAGS TEST 
#define ICMP6 RR FLAGS REQRESULT 
#define ICMP6 RR FLAGS FORCEAPPLY 
#define ICMP6 RR FLAGS SPECSITE 
#define ICMP6 RR FLAGS PREVDONE 


struct rr pco match ( 


uint8 t rpm code; 
uint8 七 rpm len; 
uint8 七 rpm ordinal; 
uint8 七 rpm matchlen; 
uint8 七 rpm minlen; 
uint8 七 rpm maxlen; 
uintl6 t rpm reserved; 


struct in6 addr rpm prefix; 


}; 


/* PCO code values */ 


0x80 
0x40 
0x20 
0x10 
0x08 
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/* match prefix part */ 


#define RPM_PCO_ADD 
#define RPM_PCO_CHANGE 


1 
2 


#define RPM PCO SETGLOBAL 3 


struct rr pco use { 

uint8 t 

uint8 t 

uint8 t 

uint8 t 

uint32 t 

uint32 t 

uint32 t 

struct in6 addr 
}; 


#define ICMP6 RR PCOUSE RAFLAGS ONLINK 
#define ICMP6 RR PCOUSE RAFLAGS AUTO 


/* use prefix part */ 

rpu uselen; 
rpu keeplen; 
rpu ramask; 
rpu raflags; 
rpu viltime; 
rpu pltime; 
rpu flags; 

rpu prefix; 


0x20 
0x10 


#if BYTE_ORDER == BIG_ENDIAN 
#define ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME 0x80000000 
#define ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME 0x40000000 


#elif BYTE_ORDER == 


LITTLE_ENDIAN 


#define ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME 0x80 
#define ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME 0x40 


#endif 
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struct rr result ( /* router renumbering result message */ 
uintl6 t rrr flags; 
uint8 t rrr ordinal; 
uint8 t rrr matchedlen; 
uint32 t rrr ifid; 


struct in6 addr rrr prefix; 


}; 


#if BYTE ORDER == BIG ENDIAN 

#define ICMP6 RR RESULT FLAGS 00B 0x0002 
#define ICMP6 RR RESULT FLAGS FORBIDDEN 0x0001 
#elif BYTE ORDER == LITTLE ENDIAN 

#define ICMP6 RR RESULT FLAGS 00B 0x0200 
#define ICMP6 RR RESULT FLAGS FORBIDDEN 0x0100 
#endif 


2.3. Address Testing Macros 


The basic API ([RFC-3493]) defines some macros for testing an IPv6 
address for certain properties. This API extends those definitions 
with additional address testing macros, defined as a result of 
including <netinet/in.h>. 


int IN6 ARE ADDR_EQUAL (const struct in6_addr *, 
const struct in6_addr *); 


This macro returns non-zero if the addresses are equal; otherwise it 
returns zero. 


2.4. Protocols File 
Many hosts provide the file /etc/protocols that contains the names of 


the various IP protocols and their protocol number (e.g., the value 
of the protocol field in the IPv4 header for that protocol, such as 1 


for ICMP). Some programs then call the function getprotobyname() to 
obtain the protocol value that is then specified as the third 
argument to the socket() function. For example, the Ping program 


contains code of the form 
struct protoent *proto; 
proto = getprotobyname ("icmp") ; 
s = socket (AF INET, SOCK RAW, proto->p proto); 
Common names are required for the new IPv6 protocols in this file, to 


provide portability of applications that call the getprotoXXX() 
functions. 
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Bis 


We define the following protocol names with the values shown. These 
are taken under http://www.iana.org/numbers.html. 


hopopt 0 # hop-by-hop options for ipv6 
ipv6 41 # ipv6 
ipv6-route 43 # routing header for ipv6 
ipv6-frag 44 f fragment header for ipv6 
esp 50 # encapsulating security payload for ipv6 
ah 51 # authentication header for ipv6 
ipv6-icmp 58 # icmp for ipv6 
ipv6-nonxt 59 f no next header for ipv6 
ipv6-opts 60 f destination options for ipv6 
IPv6 Raw Sockets 
Raw sockets bypass the transport layer (TCP or UDP). With IPv4, raw 


sockets are used to access ICMPv4, IGMPv4, and to read and write IPv4 
datagrams containing a protocol field that the kernel does not 
process. An example of the latter is a routing daemon for OSPF, 
since it uses IPv4 protocol field 89. With IPv6 raw sockets will be 
used for ICMPv6 and to read and write IPv6 datagrams containing a 
Next Header field that the kernel does not process. Examples of the 
latter are a routing daemon for OSPF for IPv6 and RSVP (protocol 
field 46). 


All data sent via raw sockets must be in network byte order and all 
data received via raw sockets will be in network byte order. This 
differs from the IPv4 raw sockets, which did not specify a byte 
ordering and used the host’s byte order for certain IP header fields. 


Another difference from IPv4 raw sockets is that complete packets 
(that is, IPv6 packets with extension headers) cannot be sent or 


received using the IPv6 raw sockets API. Instead, ancillary data 
objects are used to transfer the extension headers and hoplimit 
information, as described in Section 6. Should an application need 


access to the complete IPv6 packet, some other technique, such as the 
datalink interfaces BPF or DLPI, must be used. 


All fields except the flow label in the IPv6 header that an 
application might want to change (i.e., everything other than the 
version number) can be modified using ancillary data and/or socket 
options by the application for output. All fields except the flow 
label in a received IPv6 header (other than the version number and 
Next Header fields) and all extension headers that an application 
might want to know are also made available to the application as 
ancillary data on input. Hence there is no need for a socket option 
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similar to the IPv4 IP HDRINCL socket option and on receipt the 
application will only receive the payload i.e., the data after the 
IPv6 header and all the extension headers. 


This API does not define access to the flow label field, because 
today there is no standard usage of the field. 


When writing to a raw socket the kernel will automatically fragment 
the packet if its size exceeds the path MTU, inserting the required 


fragment headers. On input the kernel reassembles received 
fragments, so the reader of a raw socket never sees any fragment 
headers. 


When we say "an ICMPv6 raw socket" we mean a socket created by 
calling the socket function with the three arguments AF INET6, 
SOCK RAW, and IPPROTO ICMPV6. 


Most IPv4 implementations give special treatment to a raw socket 
created with a third argument to socket() of IPPROTO RAW, whose value 
is normally 255, to have it mean that the application will send down 
complete packets including the IPv4 header. (Note: This feature was 
added to IPv4 in 1988 by Van Jacobson to support traceroute, allowing 
a complete IP header to be passed by the application, before the 

IP HDRINCL socket option was added.) We note that IPPROTO RAW has no 
special meaning to an IPv6 raw socket (and the IANA currently 
reserves the value of 255 when used as a next-header field). 


3.1. Checksums 


The kernel will calculate and insert the ICMPv6 checksum for ICMPv6 
raw sockets, since this checksum is mandatory. 


For other raw IPv6 sockets (that is, for raw IPv6 sockets created 
with a third argument other than IPPROTO ICMPV6), the application 
must set the new IPV6 CHECKSUM socket option to have the kernel (1) 
compute and store a checksum for output, and (2) verify the received 
checksum on input, discarding the packet if the checksum is in error. 
This option prevents applications from having to perform source 
address selection on the packets they send. The checksum will 
incorporate the IPv6 pseudo-header, defined in Section 8.1 of [RFC- 
2460]. This new socket option also specifies an integer offset into 
the user data of where the checksum is located. 


int offset = 2; 
setsockopt (fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, 
sizeof (offset)); 
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By default, this socket option is disabled. Setting the offset to -1 
also disables the option. By disabled we mean (1) the kernel will 
not calculate and store a checksum for outgoing packets, and (2) the 
kernel will not verify a checksum for received packets. 


This option assumes the use of the 16-bit one”s complement of the 
one”s complement sum as the checksum algorithm and that the checksum 
field is aligned on a 16-bit boundary. Thus, specifying a positive 
odd value as offset is invalid, and setsockopt() will fail for such 
offset values. 


An attempt to set IPV6_CHECKSUM for an ICMPv6 socket will fail. 
Also, an attempt to set or get IPV6_CHECKSUM for a non-raw IPv6 
socket will fail. 


(Note: Since the checksum is always calculated by the kernel for an 
ICMPv6 socket, applications are not able to generate ICMPv6 packets 
with incorrect checksums (presumably for testing purposes) using this 
API.) 


3.2. ICMPV6 Type Filtering 


ICMPv4 raw sockets receive most ICMPv4 messages received by the 
kernel. (We say "most" and not "all" because Berkeley-derived 
kernels never pass echo requests, timestamp requests, or address mask 
requests to a raw socket. Instead these three messages are processed 
entirely by the kernel.) But ICMPv6 is a superset of ICMPv4, also 
including the functionality of IGMPv4 and ARPv4. This means that an 
ICMPv6 raw socket can potentially receive many more messages than 
would be received with an ICMPv4 raw socket: ICMP messages similar to 
ICMPv4, along with neighbor solicitations, neighbor advertisements, 
and the three multicast listener discovery messages. 


Most applications using an ICMPv6 raw socket care about only a small 
subset of the ICMPv6 message types. To transfer extraneous ICMPv6 
messages from the kernel to user can incur a significant overhead. 
Therefore this API includes a method of filtering ICMPv6 messages by 
the ICMPv6 type field. 


Each ICMPv6 raw socket has an associated filter whose datatype is 
defined as 


struct icmp6 filter; 
This structure, along with the macros and constants defined later in 


this section, are defined as a result of including the 
<netinet/icmp6.h>. 
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The current filter is fetched and stored using getsockopt() and 
setsockopt() with a level of IPPROTO ICMPV6 and an option name of 
ICMP6 FILTER. 


Six macros operate on an icmp6 filter structure: 


void ICMP6 FILTER SETPASSALL (struct icmp6 filter *); 
void ICMP6 FILTER SETBLOCKALL(struct icmp6 filter *); 


void ICMP6 FILTER SETPASS ( int, struct icmpé6 filter *); 
void ICMP6 FILTER SETBLOCK( int, struct icmpé6 filter *); 


int ICMP6 FILTER WILLPASS (int, 
const struct icmp6 filter *); 
int ICMP6 FILTER WILLBLOCK (int, 

const struct icmp6 filter *); 


The first argument to the last four macros (an integer) is an ICMPV6 
message type, between 0 and 255. The pointer argument to all six 
macros is a pointer to a filter that is modified by the first four 
macros and is examined by the last two macros. 


The first two macros, SETPASSALL and SETBLOCKALL, let us specify that 
all ICMPv6 messages are passed to the application or that all ICMPV6 
messages are blocked from being passed to the application. 


The next two macros, SETPASS and SETBLOCK, let us specify that 
messages of a given ICMPV6 type should be passed to the application 
or not passed to the application (blocked). 


The final two macros, WILLPASS and WILLBLOCK, return true or false 
depending whether the specified message type is passed to the 
application or blocked from being passed to the application by the 
filter pointed to by the second argument. 


When an ICMPv6 raw socket is created, it will by default pass all 
ICMPv6 message types to the application. 


As an example, a program that wants to receive only router 
advertisements could execute the following: 


struct icmp6 filter myfilt; 
fd = socket (AF_INET6, SOCK_RAW, IPPROTO_ICMPV6) ; 
ICMP6 FILTER SETBLOCKALL (&myfilt) ; 


ICMP6 FILTER SETPASS(ND ROUTER ADVERT, &myfilt); 
setsockopt (fd, IPPROTO ICMPV6, ICMP6 FILTER, &myfilt, 
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sizeof (myfilt)); 


The filter structure is declared and then initialized to block all 
messages types. The filter structure is then changed to allow router 
advertisement messages to be passed to the application and the filter 
is installed using setsockopt(). 


In order to clear an installed filter the application can issue a 
setsockopt for ICMP6_FILTER with a zero length. When no such filter 
has been installed, getsockopt() will return the kernel default 
filter. 


The icmp6_filter structure is similar to the fd_set datatype used 
with the select() function in the sockets API. The icmp6_filter 
structure is an opaque datatype and the application should not care 
how it is implemented. All the application does with this datatype 
is allocate a variable of this type, pass a pointer to a variable of 
this type to getsockopt() and setsockopt(), and operate on a variable 
of this type using the six macros that we just defined. 


Nevertheless, it is worth showing a simple implementation of this 
datatype and the six macros. 


struct icmp6_filter { 
uint32_t icmp6_filt[8]; /* 8*32 = 256 bits */ 
}; 


#define ICMP6 FILTER WILLPASS (type, filterp) \ 
((((filterp)->icmp6_filt[(type) >> 5]) & \ 
(1 << ((type) & 31))) != 0) 
#define ICMP6 FILTER WILLBLOCK (type, filterp) \ 
((((filterp)->icmpé6 filt[ (type) >> 5]) & \ 
(1 << ((type) & 31))) == 0) 
#define ICMP6 FILTER SETPASS(type, filterp) \ 
((((filterp)->icmp6 filt[ (type) >> 5]) |= N 
(1 << ((type) & 31)))) 
#define ICMP6 FILTER SETBLOCK (type, filterp) \ 
((((filterp)->icmp6_filt[(type) >> 5]) &= \ 
“(1 << ((type) & 31)))) 
#define ICMP6_FILTER_SETPASSALL(filterp) \ 
memset ((filterp), OxFF, sizeof(struct icmp6_filter) ) 
#define ICMP6_FILTER_SETBLOCKALL(filterp) \ 
memset ((filterp), 0, sizeof(struct icmpé6 filter)) 


(Note: These sample definitions have two limitations that an 
implementation may want to change. The first four macros evaluate 
their first argument two times. The second two macros require the 
inclusion of the <string.h> header for the memset() function.) 
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3.3.  ICMPv6 Verification of Received Packets 


The protocol stack will verify the ICMPv6 checksum and discard any 
packets with invalid checksums. 


An implementation might perform additional validity checks on the 
ICMPv6 message content and discard malformed packets. However, a 
portable application must not assume that such validity checks have 
been performed. 


The protocol stack should not automatically discard packets if the 
ICMP type is unknown to the stack. For extensibility reasons 
received ICMP packets with any type (informational or error) must be 
passed to the applications (subject to ICMP6_FILTER filtering on the 
type value and the checksum verification). 


4. Access to IPv6 and Extension Headers 


Applications need to be able to control IPv6 header and extension 
header content when sending as well as being able to receive the 
content of these headers. This is done by defining socket option 
types which can be used both with setsockopt and with ancillary data. 
Ancillary data is discussed in Appendix A. The following optional 
information can be exchanged between the application and the kernel: 


The send/receive interface and source/destination address, 
The hop limit, 

Next hop address, 

The traffic class, 

Routing header, 

Hop-by-Hop options header, and 

Destination options header. 


YHODUBWNE 


First, to receive any of this optional information (other than the 
next hop address, which can only be set) on a UDP or raw socket, the 


application must call setsockopt() to turn on the corresponding flag: 

int on= 1; 

setsockopt (fd, IPPROTO_IPV6, IPV6_RECVPKTINFO, &on, sizeof(on)); 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVHOPLIMIT, &on, sizeof(on)); 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVRTHDR, &on, sizeof(on)); 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVHOPOPTS, &on, sizeof(on)); 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVDSTOPTS, &on, sizeof(on)); 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVTCLASS, &on, sizeof(on)); 
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When any of these options are enabled, the corresponding data is 
returned as control information by recvmsg(), as one or more 
ancillary data objects. 


This document does not define how to receive the optional information 
on a TCP socket. See Section 4.1 for more details. 


Two different mechanisms exist for sending this optional information: 


1. Using setsockopt to specify the option content for a socket. 
These are known "sticky" options since they affect all transmitted 
packets on the socket until either a new setsockopt is done or the 
options are overridden using ancillary data. 


2. Using ancillary data to specify the option content for a single 
datagram. This only applies to datagram and raw sockets; not to 
TCP sockets. 


The three socket option parameters and the three cmsghdr fields that 
describe the options/ancillary data objects are summarized as: 


opt level/ optname/ optval/ 

cmsg_level cmsg_type cmsg_data[] 

IPPROTO IPV6 IPV6_PKTINFO in6 pktinfo structure 
IPPROTO IPV6 IPV6_HOPLIMIT int 

IPPROTO IPV6 IPV6_NEXTHOP socket address structure 
IPPROTO IPV6 IPV6_RTHDR ip6 rthdr structure 
IPPROTO IPV6 IPV6_HOPOPTS ip6 hbh structure 
IPPROTO IPV6 IPV6_DSTOPTS ip6 dest structure 
IPPROTO IPV6 IPV6_RTHDRDSTOPTS ip6 dest structure 
IPPROTO IPV6 IPV6_TCLASS int 


(Note: IPV6 HOPLIMIT can be used as ancillary data items only) 
All these options are described in detail in Section 6, 7, 8 and 9. 
All the constants beginning with IPV6 are defined as a result of 


including <netinet/in.h>. 


Note: We intentionally use the same constant for the cmsg_level 


member as is used as the second argument to getsockopt() and 
setsockopt() (what is called the "level"), and the same constant for 
the cmsg_type member as is used as the third argument to getsockopt () 
and setsockopt() (what is called the "option name"). 
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Issuing getsockopt() for the above options will return the sticky 
option value i.e., the value set with setsockopt(). If no sticky 
option value has been set getsockopt() will return the following 
values: 


- For the IPV6 PKTINFO option, it will return an in6 pktinfo 
structure with ipi6 addr being in6addr any and ipi6 ifindex being 
zero. 


- For the IPV6_TCLASS option, it will return the kernel default 
value. 


- For other options, it will indicate the lack of the option value 
with optlen being zero. 


The application does not explicitly need to access the data 
structures for the Routing header, Hop-by-Hop options header, and 
Destination options header, since the API to these features is 
through a set of inet6 rth XXX() and inet6 opt XXX() functions that 
we define in Section 7 and Section 10. Those functions simplify the 
interface to these features instead of requiring the application to 
know the intimate details of the extension header formats. 


When specifying extension headers, this API assumes the header 
ordering and the number of occurrences of each header as described in 
[RFC-2460]. More details about the ordering issue will be discussed 
in Section 12. 


4.1. TCP Implications 


It is not possible to use ancillary data to transmit the above 
options for TCP since there is not a one-to-one mapping between send 
operations and the TCP segments being transmitted. Instead an 
application can use setsockopt to specify them as sticky options. 
When the application uses setsockopt to specify the above options it 
is expected that TCP will start using the new information when 
sending segments. However, TCP may or may not use the new 
information when retransmitting segments that were originally sent 
when the old sticky options were in effect. 


It is unclear how a TCP application can use received information 
(such as extension headers) due to the lack of mapping between 
received TCP segments and receive operations. In particular, the 
received information could not be used for access control purposes 
like on UDP and raw sockets. 
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This specification therefore does not define how to get the received 
information on TCP sockets. The result of the IPV6 RECVxxx options 
on a TCP socket is undefined as well. 


4.2. UDP and Raw Socket Implications 


The receive behavior for UDP and raw sockets is quite 
straightforward. After the application has enabled an IPV6_RECVxxx 
socket option it will receive ancillary data items for every 
recvmsg() call containing the requested information. However, if the 
information is not present in the packet the ancillary data item will 
not be included. For example, if the application enables 

IPV6 RECVRTHDR and a received datagram does not contain a Routing 
header there will not be an IPV6_RTHDR ancillary data item. Note 
that due to buffering in the socket implementation there might be 
some packets queued when an IPV6_RECVxxx option is enabled and they 
might not have the ancillary data information. 


For sending the application has the choice between using sticky 
options and ancillary data. The application can also use both having 
the sticky options specify the "default" and using ancillary data to 
override the default options. 


When an ancillary data item is specified in a call to sendmsg(), the 
item will override an existing sticky option of the same name (if 
previously specified). For example, if the application has set 
IPV6_RTHDR using a sticky option and later passes IPV6_RTHDR as 
ancillary data this will override the IPV6_RTHDR sticky option and 
the routing header of the outgoing packet will be from the ancillary 
data item, not from the sticky option. Note, however, that other 
sticky options than IPV6_RTHDR will not be affected by the IPV6_RTHDR 
ancillary data item; the overriding mechanism only works for the same 
type of sticky options and ancillary data items. 


(Note: the overriding rule is different from the one in RFC 2292. In 
RFC 2292, an ancillary data item overrode all sticky options 
previously defined. This was reasonable, because sticky options 
could only be specified as a set by a single socket option. However, 
in this API, each option is separated so that it can be specified as 
a single sticky option. Additionally, there are much more ancillary 
data items and sticky options than in RFC 2292, including ancillary- 
only one. Thus, it should be natural for application programmers to 
separate the overriding rule as well.) 


An application can also temporarily disable a particular sticky 
option by specifying a corresponding ancillary data item that could 
disable the sticky option when being used as an argument for a socket 
option. For example, if the application has set IPV6_HOPOPTS as a 
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sticky option and later passes IPV6 HOPOPTS with a zero length as an 
ancillary data item, the packet will not have a Hop-by-Hop options 
header. 


5. Extensions to Socket Ancillary Data 


This specification uses ancillary data as defined in Posix with some 
compatible extensions, which are described in the following 


subsections. Section 20 will provide a detailed overview of 
ancillary data and related structures and macros, including the 
extensions. 


5.1.  CMSG NXTHDR 


struct cmsghdr *CMSG NXTHDR(const struct msghdr *mhdr, 
const struct cmsghdr *cmsg); 


CMSG NXTHDR() returns a pointer to the cmsghdr structure describing 
the next ancillary data object. Mhdr is a pointer to a msghdr 
structure and cmsg is a pointer to a cmsghdr structure. If there is 
not another ancillary data object, the return value is NULL. 


The following behavior of this macro is new to this API: if the value 
of the cmsg pointer is NULL, a pointer to the cmsghdr structure 
describing the first ancillary data object is returned. That is, 
CMSG_NXTHDR(mhdr, NULL) is equivalent to CMSG_FIRSTHDR(mhdr) . If 
there are no ancillary data objects, the return value is NULL. 


5.2.  CMSG SPACE 
socklen t CMSG SPACE (socklen t length); 


This macro is new with this API. Given the length of an ancillary 
data object, CMSG SPACE() returns an upper bound on the space 
required by the object and its cmsghdr structure, including any 
padding needed to satisfy alignment requirements. This macro can be 
used, for example, when allocating space dynamically for the 
ancillary data. This macro should not be used to initialize the 
cmsg len member of a cmsghdr structure; instead use the CMSG LEN() 
macro. 
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5.3. CMSG_LEN 
socklen_t CMSG_LEN (socklen_t length); 


This macro is new with this API. Given the length of an ancillary 
data object, CMSG_LEN() returns the value to store in the cmsg_len 
member of the cmsghdr structure, taking into account any padding 
needed to satisfy alignment requirements. 


Note the difference between CMSG_SPACE() and CMSG_LEN(), shown also 
in the figure in Section 20.2: the former accounts for any required 
padding at the end of the ancillary data object and the latter is the 
actual length to store in the cmsg_len member of the ancillary data 
object. 


6. Packet Information 


There are five pieces of information that an application can specify 
for an outgoing packet using ancillary data: 


the source IPv6 address, 

the outgoing interface index, 

the outgoing hop limit, 

the next hop address, and 

the outgoing traffic class value. 


UO AUNE 


Four similar pieces of information can be returned for a received 
packet as ancillary data: 


the destination IPv6 address, 

the arriving interface index, 

the arriving hop limit, and 

the arriving traffic class value. 


RUNKE 


The first two pieces of information are contained in an in6 pktinfo 
structure that is set with setsockopt() or sent as ancillary data 
with sendmsg() and received as ancillary data with recvmsg(). This 
structure is defined as a result of including <netinet/in.h>. 


struct in6_pktinfo { 
struct in6_addr ipi6 addr; /* src/dst IPv6 address */ 
unsigned int ipi6 ifindex; /* send/recv interface index */ 


}; 


In the socket option and cmsghdr level will be IPPROTO_IPV6, the type 
will be IPV6 PKTINFO, and the first byte of the option value and 

cmsg data[] will be the first byte of the in6 pktinfo structure. An 
application can clear any sticky IPV6 PKTINFO option by doing a 
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"regular" setsockopt with ipi6 addr being in6addr any and 
ipi6 ifindex being zero. 


This information is returned as ancillary data by recvmsg() only if 
the application has enabled the IPV6 RECVPKTINFO socket option: 


int on = 1; 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVPKTINFO, &on, sizeof(on)); 


(Note: The hop limit is not contained in the in6 pktinfo structure 
for the following reason. Some UDP servers want to respond to client 
requests by sending their reply out the same interface on which the 
request was received and with the source IPv6 address of the reply 
equal to the destination IPv6 address of the request. To do this the 
application can enable just the IPV6 RECVPKTINFO socket option and 
then use the received control information from recvmsg() as the 
outgoing control information for sendmsg(). The application need not 
examine or modify the in6 pktinfo structure at all. But if the hop 
limit were contained in this structure, the application would have to 
parse the received control information and change the hop limit 
member, since the received hop limit is not the desired value for an 
outgoing packet.) 


6.1. Specifying/Receiving the Interface 


Interfaces on an IPv6 node are identified by a small positive 
integer, as described in Section 4 of [RFC-3493]. That document also 
describes a function to map an interface name to its interface index, 
a function to map an interface index to its interface name, anda 
function to return all the interface names and indexes. Notice from 
this document that no interface is ever assigned an index of 0. 


When specifying the outgoing interface, if the ipi6 ifindex value is 
0, the kernel will choose the outgoing interface. 


The ordering among various options that can specify the outgoing 
interface, including IPV6_PKTINFO, is defined in Section 6.7. 


When the IPV6_RECVPKTINFO socket option is enabled, the received 


interface index is always returned as the ipi6 ifindex member of the 
in6 pktinfo structure. 
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6.2. Specifying/Receiving Source/Destination Address 


The source IPv6 address can be specified by calling bind() before 
each output operation, but supplying the source address together with 
the data requires less overhead (i.e., fewer system calls) and 
requires less state to be stored and protected in a multithreaded 
application. 


When specifying the source IPv6 address as ancillary data, if the 
ipi6 addr member of the in6 pktinfo structure is the unspecified 
address (IN6ADDR ANY INIT or in6addr any), then (a) if an address is 
currently bound to the socket, it is used as the source address, or 
(b) if no address is currently bound to the socket, the kernel will 
choose the source address. If the ipi6 addr member is not the 
unspecified address, but the socket has already bound a source 
address, then the ipi6 addr value overrides the already-bound source 
address for this output operation only. 


The kernel must verify that the requested source address is indeed a 
unicast address assigned to the node. When the address is a scoped 
one, there may be ambiguity about its scope zone. This is 
particularly the case for link-local addresses. In such a case, the 
kernel must first determine the appropriate scope zone based on the 
zone of the destination address or the outgoing interface (if known), 
then qualify the address. This also means that it is not feasible to 
specify the source address for a non-binding socket by the 
IPV6_PKTINFO sticky option, unless the outgoing interface is also 
specified. The application should simply use bind() for such 
purposes. 


IPV6_PKTINFO can also be used as a sticky option for specifying the 
socket’s default source address. However, the ipi6 addr member must 
be the unspecified address for TCP sockets, because it is not 
possible to dynamically change the source address of a TCP 
connection. When the IPV6_PKTINFO option is specified for a TCP 


socket with a non-unspecified address, the call will fail. This 
restriction should be applied even before the socket binds a specific 
address. 


When the iné6 pktinfo structure is returned as ancillary data by 
recvmsg(), the ipié_addr member contains the destination IPv6 address 
from the received packet. 


6.3. Specifying/Receiving the Hop Limit 
The outgoing hop limit is normally specified with either the 


IPV6_UNICAST_HOPS socket option or the IPV6_MULTICAST_HOPS socket 
option, both of which are described in [RFC-3493]. Specifying the 
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hop limit as ancillary data lets the application override either the 
kernel’s default or a previously specified value, for either a 
unicast destination or a multicast destination, for a single output 
operation. Returning the received hop limit is useful for IPv6 
applications that need to verify that the received hop limit is 255 
(e.g., that the packet has not been forwarded). 


The received hop limit is returned as ancillary data by recvmsg() 
only if the application has enabled the IPV6_RECVHOPLIMIT socket 
option: 


int on= 1; 
setsockopt (fd, IPPROTO_IPV6, IPV6_RECVHOPLIMIT, &on, sizeof(on)); 


In the cmsghdr structure containing this ancillary data, the 
cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be 
IPV6_HOPLIMIT, and the first byte of cmsg_data[] will be the first 
byte of the integer hop limit. 


Nothing special need be done to specify the outgoing hop limit: just 
specify the control information as ancillary data for sendmsg(). As 
specified in [RFC-3493], the interpretation of the integer hop limit 
value is 


<a: return an error of EINVAL 
> === å use kernel default 

0 <= x <= 255: use x 

x >= 256: return an error of EINVAL 


This API defines IPV6_HOPLIMIT as an ancillary-only option, that is, 
the option name cannot be used as a socket option. This is because 
[RFC-3493] has more fine-grained socket options; IPV6_UNICAST_HOPS 
and IPV6_MULTICAST_HOPS. 


6.4. Specifying the Next Hop Address 


The IPV6_NEXTHOP ancillary data object specifies the next hop for the 
datagram as a socket address structure. In the cmsghdr structure 
containing this ancillary data, the cmsg_level member will be 
IPPROTO_IPV6, the cmsg_type member will be IPV6_NEXTHOP, and the 
first byte of cmsg_data[] will be the first byte of the socket 
address structure. 


This is a privileged option. (Note: It is implementation defined and 
beyond the scope of this document to define what "privileged" means. 
Unix systems use this term to mean the process must have an effective 
user ID of 0.) 
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This API only defines the case where the socket address contains an 
IPv6 address (i.e., the sa family member is AF INET6). And, in this 
case, the node identified by that address must be a neighbor of the 
sending host. If that address equals the destination IPv6 address of 
the datagram, then this is equivalent to the existing SO DONTROUTE 
socket option. 


This option does not have any meaning for multicast destinations. In 
such a case, the specified next hop will be ignored. 


When the outgoing interface is specified by IPV6_PKTINFO as well, the 
next hop specified by this option must be reachable via the specified 
interface. 


In order to clear a sticky IPV6_NEXTHOP option the application must 
issue a setsockopt for IPV6_NEXTHOP with a zero length. 


6.5. Specifying/Receiving the Traffic Class value 


The outgoing traffic class is normally set to 0. Specifying the 
traffic class as ancillary data lets the application override either 
the kernel’s default or a previously specified value, for either a 
unicast destination or a multicast destination, for a single output 
operation. Returning the received traffic class is useful for 
programs such as a diffserv debugging tool and for user level ECN 
(explicit congestion notification) implementation. 


The received traffic class is returned as ancillary data by recvmsg() 
only if the application has enabled the IPV6 RECVTCLASS socket 
option: 


int on = 1; 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVTCLASS, &on, sizeof(on)); 


In the cmsghdr structure containing this ancillary data, the 

cmsg level member will be IPPROTO IPV6, the cmsg type member will be 
IPV6 TCLASS, and the first byte of cmsg_data[] will be the first byte 
of the integer traffic class. 


To specify the outgoing traffic class value, just specify the control 
information as ancillary data for sendmsg() or using setsockopt(). 
Just like the hop limit value, the interpretation of the integer 
traffic class value is 


KIL aS return an error of EINVAL 
x == -l: use kernel default 

0 <= x <= 255: use x 

x >= 256: return an error of EINVAL 
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6. 


6. 


6. 


7. 


In order to clear a sticky IPV6_TCLASS option the application can 
specify -1 as the value. 


There are cases where the kernel needs to control the traffic class 
value and conflicts with the user-specified value on the outgoing 
traffic. An example is an implementation of ECN in the kernel, 
setting 2 bits of the traffic class value. In such cases, the kernel 
should override the user-specified value. On the incoming traffic, 
the kernel may mask some of the bits in the traffic class field. 


Additional Errors with sendmsg() and setsockopt () 


With the IPV6_PKTINFO socket option there are no additional errors 
possible with the call to recvmsg(). But when specifying the 
outgoing interface or the source address, additional errors are 
possible from sendmsg() or setsockopt(). Note that some 
implementations might only be able to return this type of errors for 
setsockopt(). The following are examples, but some of these may not 
be provided by some implementations, and some implementations may 
define additional errors: 


ENXIO The interface specified by ipi6 ifindex does not exist. 


ENETDOWN The interface specified by ipi6 ifindex is not enabled 
for IPv6 use. 


EADDRNOTAVAIL ipi6 ifindex specifies an interface but the address 
ipi6 addr is not available for use on that interface. 


EHOSTUNREACH No route to the destination exists over the interface 
specified by ipi6 ifindex. 


Summary of Outgoing Interface Selection 


This document and [RFC-3493] specify various methods that affect the 
selection of the packet’s outgoing interface. This subsection 
summarizes the ordering among those in order to ensure deterministic 
behavior. 


For a given outgoing packet on a given socket, the outgoing interface 
is determined in the following order: 


1. if an interface is specified in an IPV6_PKTINFO ancillary data 
item, the interface is used. 


2. otherwise, if an interface is specified in an IPV6_PKTINFO sticky 
option, the interface is used. 
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3. otherwise, if the destination address is a multicast address and 
the IPV6 MULTICAST IF socket option is specified for the socket, 
the interface is used. 


4. otherwise, if an IPV6 NEXTHOP ancillary data item is specified, 
the interface to the next hop is used. 


5. otherwise, if an IPV6 NEXTHOP sticky option is specified, the 
interface to the next hop is used. 


6. otherwise, the outgoing interface should be determined in an 
implementation dependent manner. 


The ordering above particularly means if the application specifies an 
interface by the IPV6 MULTICAST IF socket option (described in [RFC- 
34931) as well as specifying a different interface by the 

IPV6 PKTINFO sticky option, the latter will override the former for 
every multicast packet on the corresponding socket. The reason for 
the ordering comes from expectation that the source address is 
specified as well and that the pair of the address and the outgoing 
interface should be preferred. 


In any case, the kernel must also verify that the source and 
destination addresses do not break their scope zones with regard to 
the outgoing interface. 


7. Routing Header Option 


Source routing in IPv6 is accomplished by specifying a Routing header 
as an extension header. There can be different types of Routing 
headers, but IPv6 currently defines only the Type 0 Routing header 
[RFC-2460]. This type supports up to 127 intermediate nodes (limited 
by the length field in the extension header). With this maximum 
number of intermediate nodes, a source, and a destination, there are 
128 hops. 


Source routing with the IPv4 sockets API (the IP_OPTIONS socket 
option) requires the application to build the source route in the 
format that appears as the IPv4 header option, requiring intimate 
knowledge of the IPv4 options format. This IPv6 API, however, 
defines six functions that the application calls to build and examine 
a Routing header, and the ability to use sticky options or ancillary 
data to communicate this information between the application and the 
kernel using the IPV6_RTHDR option. 
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Three functions build a Routing header: 


inet6_rth_space () - return #bytes required for Routing header 
inet6_rth_init () - initialize buffer data for Routing header 
inet6_rth_add() - add one IPv6 address to the Routing header 


Three functions deal with a returned Routing header: 


inet6 rth reverse() - reverse a Routing header 
inet6_rth_segments() - return #segments in a Routing header 
inet 6_rth_getaddr () fetch one address from a Routing header 


The function prototypes for these functions are defined as a result 
of including <netinet/in.h>. 


To receive a Routing header the application must enable the 
IPV6 RECVRTHDR socket option: 


int on = 1; 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVRTHDR, &on, sizeof(on)); 


Each received Routing header is returned as one ancillary data object 
described by a cmsghdr structure with cmsg type set to IPV6 RTHDR. 
When multiple Routing headers are received, multiple ancillary data 
objects (with cmsg type set to IPV6 RTHDR) will be returned to the 
application. 


To send a Routing header the application specifies it either as 


ancillary data in a call to sendmsg() or using setsockopt(). For the 
sending side, this API assumes the number of occurrences of the 
Routing header as described in [RFC-2460]. That is, applications can 


only specify at most one outgoing Routing header. 


The application can remove any sticky Routing header by calling 
setsockopt() for IPV6_RTHDR with a zero option length. 


When using ancillary data a Routing header is passed between the 
application and the kernel as follows: The cmsg_level member has a 
value of IPPROTO_IPV6 and the cmsg_type member has a value of 
IPV6_RTHDR. The contents of the cmsg_data[] member is implementation 
dependent and should not be accessed directly by the application, but 
should be accessed using the six functions that we are about to 
describe. 


The following constant is defined as a result of including the 
<netinet/in.h>: 


#define IPV6 RTHDR TYPE 0 0 /* IPv6 Routing header type 0 */ 
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When a Routing header is specified, the destination address specified 
for connect(), sendto(), or sendmsg() is the final destination 
address of the datagram. The Routing header then contains the 
addresses of all the intermediate nodes. 


7.1. ineté6 rth space 
socklen t inet6 rth space(int type, int segments); 


This function returns the number of bytes required to hold a Routing 
header of the specified type containing the specified number of 
segments (addresses). For an IPv6 Type 0 Routing header, the number 
of segments must be between 0 and 127, inclusive. The return value 
is just the space for the Routing header. When the application uses 
ancillary data it must pass the returned length to CMSG SPACE() to 
determine how much memory is needed for the ancillary data object 
(including the cmsghdr structure). 


If the return value is 0, then either the type of the Routing header 
is not supported by this implementation or the number of segments is 
invalid for this type of Routing header. 


(Note: This function returns the size but does not allocate the space 
required for the ancillary data. This allows an application to 
allocate a larger buffer, if other ancillary data objects are 
desired, since all the ancillary data objects must be specified to 
sendmsg() as a single msg control buffer.) 


7.2. inet6 rth init 


void *inet6_rth_init (void *bp, socklen t bp len, int type, 
int segments); 


This function initializes the buffer pointed to by bp to contain a 
Routing header of the specified type and sets ip6r len based on the 
segments parameter. bp len is only used to verify that the buffer is 
large enough. The ipér segleft field is set to zero; ineté6 rth add() 
will increment it. 


When the application uses ancillary data the application must 
initialize any cmsghdr fields. 


The caller must allocate the buffer and its size can be determined by 
calling inet6 rth space(). 


Upon success the return value is the pointer to the buffer (bp), and 


this is then used as the first argument to the inet6 rth add() 
function. Upon an error the return value is NULL. 
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7.3.  inet6 rth add 
int inet6_rth_add(void *bp, const struct in6_addr *addr); 


This function adds the IPv6 address pointed to by addr to the end of 
the Routing header being constructed. 


If successful, the segleft member of the Routing Header is updated to 
account for the new address in the Routing header and the return 
value of the function is 0. Upon an error the return value of the 
function is -1. 


7.4. inet6 rth reverse 
int inet6 rth reverse(const void *in, void *out); 


This function takes a Routing header extension header (pointed to by 
the first argument) and writes a new Routing header that sends 
datagrams along the reverse of that route. The function reverses the 
order of the addresses and sets the segleft member in the new Routing 
header to the number of segments. Both arguments are allowed to 
point to the same buffer (that is, the reversal can occur in place). 


The return value of the function is 0 on success, or -1 upon an 
error. 


7.5. inet6_rth segments 
int inet6_rth_segments (const void *bp); 
This function returns the number of segments (addresses) contained in 
the Routing header described by bp. On success the return value is 
zero or greater. The return value of the function is -1 upon an 
error. 
7.6. inet6_rth_getaddr 
struct in6_addr *inet6_rth_getaddr(const void *bp, int index); 
This function returns a pointer to the IPv6 address specified by 
index (which must have a value between 0 and one less than the value 
returned by inet6_rth_segments()) in the Routing header described by 
bp. An application should first call inet6_rth_segments() to obtain 


the number of segments in the Routing header. 


Upon an error the return value of the function is NULL. 
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8. 


Hop-By-Hop Options 


A variable number of Hop-by-Hop options can appear in a single Hop- 
by-Hop options header. Each option in the header is TLV-encoded with 
a type, length, and value. This IPv6 API defines seven functions 
that the application calls to build and examine a Hop-by Hop options 
header, and the ability to use sticky options or ancillary data to 
communicate this information between the application and the kernel. 
This uses the IPV6_HOPOPTS for a Hop-by-Hop options header. 


Today several Hop-by-Hop options are defined for IPv6. Two pad 
options, Padl and PadN, are for alignment purposes and are 
automatically inserted by the inet6_opt_XXX() routines and ignored by 
the inet6 opt XXX() routines on the receive side. This section of 
the API is therefore defined for other (and future) Hop-by-Hop 
options that an application may need to specify and receive. 


Four functions build an options header: 


inet6 opt init() - initialize buffer data for options header 

inet6 opt append() - add one TLV option to the options header 

inet6 opt finish() - finish adding TLV options to the options 
header 


inet6 opt set val() add one component of the option content to 


the option 


Three functions deal with a returned options header: 


inet6 opt next () - extract the next option from the options 
header 

inet6 opt find() - extract an option of a specified type from 
the header 

inet6 opt get val() - retrieve one component of the option 
content 


Individual Hop-by-Hop options (and Destination options, which are 
described in Section 9 and are very similar to the Hop-by-Hop 
options) may have specific alignment requirements. For example, the 
4-byte Jumbo Payload length should appear on a 4-byte boundary, and 
IPv6 addresses are normally aligned on an 8-byte boundary. These 
requirements and the terminology used with these options are 


discussed in Section 4.2 and Appendix B of [RFC-2460]. The alignment 
of first byte of each option is specified by two values, called x and 
y, written as "xn + y". This states that the option must appear at 


an integer multiple of x bytes from the beginning of the options 
header (x can have the values 1, 2, 4, or 8), plus y bytes (y can 
have a value between 0 and 7, inclusive). The Padl and PadN options 
are inserted as needed to maintain the required alignment. The 
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functions below need to know the alignment of the end of the option 
(which is always in the form "xn," where x can have the values 1, 2, 
4, or 8) and the total size of the data portion of the option. These 
are passed as the "align" and "len" arguments to inet6 opt append(). 


Multiple Hop-by-Hop options must be specified by the application by 
placing them in a single extension header. 


Finally, we note that use of some Hop-by-Hop options or some 
Destination options, might require special privilege. That is, 
normal applications (without special privilege) might be forbidden 
from setting certain options in outgoing packets, and might never see 
certain options in received packets. 


8.1. Receiving Hop-by-Hop Options 


To receive a Hop-by-Hop options header the application must enable 
the IPV6 RECVHOPOPTS socket option: 


int on = 1; 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVHOPOPTS, &on, sizeof(on)); 


When using ancillary data a Hop-by-hop options header is passed 
between the application and the kernel as follows: The cmsg level 
member will be IPPROTO IPV6 and the cmsg type member will be 

IPV6 HOPOPTS. These options are then processed by calling the 
inet6 opt next(), inet6 opt find(), and inet6 opt get val() 
functions, described in Section 10. 


8.2. Sending Hop-by-Hop Options 


To send a Hop-by-Hop options header, the application specifies the 
header either as ancillary data in a call to sendmsg() or using 
setsockopt () . 


The application can remove any sticky Hop-by-Hop options header by 
calling setsockopt() for IPV6 HOPOPTS with a zero option length. 


All the Hop-by-Hop options must be specified by a single ancillary 
data object. The cmsg_level member is set to IPPROTO_IPV6 and the 
cmsg_type member is set to IPV6_HOPOPTS. The option is normally 
constructed using the inet6_opt_init(), inet6_opt_append(), 
inet6 opt finish(), and inet6_opt_set_val() functions, described in 
Section 10. 


Additional errors may be possible from sendmsg() and setsockopt() if 
the specified option is in error. 
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Destination Options 


A variable number of Destination options can appear in one or more 
Destination options headers. As defined in [RFC-2460], a Destination 
options header appearing before a Routing header is processed by the 
first destination plus any subsequent destinations specified in the 
Routing header, while a Destination options header that is not 
followed by a Routing header is processed only by the final 
destination. As with the Hop-by-Hop options, each option ina 
Destination options header is TLV-encoded with a type, length, and 
value. 


1. Receiving Destination Options 


To receive Destination options header the application must enable the 
IPV6 RECVDSTOPTS socket option: 


int on = 1; 
setsockopt (fd, IPPROTO IPV6, IPV6 RECVDSTOPTS, &on, sizeof(on)); 


Each Destination options header is returned as one ancillary data 
object described by a cmsghdr structure with cmsg level set to 
IPPROTO IPV6 and cmsg type set to IPV6 DSTOPTS. 


These options are then processed by calling the inet6 opt next (), 
inet6 opt find(), and inet6 opt get value() functions. 


2. Sending Destination Options 


To send a Destination options header, the application specifies it 
either as ancillary data in a call to sendmsg() or using 
setsockopt () . 


The application can remove any sticky Destination options header by 
calling setsockopt() for IPV6 RTHDRDSTOPTS/IPV6 DSTOPTS with a zero 
option length. 


This API assumes the ordering about extension headers as described in 
[RFC-2460]. Thus, one set of Destination options can only appear 
before a Routing header, and one set can only appear after a Routing 
header (or in a packet with no Routing header). Each set can consist 
of one or more options but each set is a single extension header. 


Today all destination options that an application may want to specify 
can be put after (or without) a Routing header. Thus, applications 
should usually need IPV6_DSTOPTS only and should avoid using 

IPV6 RTHDRDSTOPTS whenever possible. 
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When using ancillary data a Destination options header is passed 
between the application and the kernel as follows: The set preceding 
a Routing header are specified with the cmsg level member set to 
IPPROTO IPV6 and the cmsg type member set to IPV6 RTHDRDSTOPTS. Any 
setsockopt or ancillary data for IPV6 RTHDRDSTOPTS is silently 
ignored when sending packets unless a Routing header is also 
specified. Note that the "Routing header" here means the one 
specified by this API. Even when the kernel inserts a routing header 
in its internal routine (e.g., in a mobile IPv6 stack), the 
Destination options header specified by IPV6_RTHDRDSTOPTS will still 
be ignored unless the application explicitly specifies its own 
Routing header. 


The set of Destination options after a Routing header, which are also 
used when no Routing header is present, are specified with the 
cmsg_level member is set to IPPROTO_IPV6 and the cmsg_type member is 
set to IPV6_DSTOPTS. 


The Destination options are normally constructed using the 
inet6 opt init(), inet6_opt_append(), inet6_opt_finish(), and 
inet6 opt set val() functions, described in Section 10. 


Additional errors may be possible from sendmsg() and setsockopt() if 
the specified option is in error. 


Hop-by-Hop and Destination Options Processing 


Building and parsing the Hop-by-Hop and Destination options is 
complicated for the reasons given earlier. We therefore define a set 
of functions to help the application. These functions assume the 
formatting rules specified in Appendix B in [RFC-2460] i.e., that the 
largest field is placed last in the option. 


The function prototypes for these functions are defined as a result 
of including <netinet/in.h>. 


The first 3 functions (init, append, and finish) are used both to 
calculate the needed buffer size for the options, and to actually 
encode the options once the application has allocated a buffer for 
the header. In order to only calculate the size the application must 
pass a NULL extbuf and a zero extlen to those functions. 
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1. inet6 opt init 
int inet6_opt_init (void *extbuf, socklen t extlen); 


This function returns the number of bytes needed for the empty 
extension header i.e., without any options. If extbuf is not NULL it 
also initializes the extension header to have the correct length 
field. In that case if the extlen value is not a positive (i.e., 
non-zero) multiple of 8 the function fails and returns -1. 


(Note: since the return value on success is based on a "constant" 
parameter, i.e., the empty extension header, an implementation may 
return a constant value. However, this specification does not 
require the value be constant, and leaves it as implementation 
dependent. The application should not assume a particular constant 
value as a successful return value of this function.) 


.2. inet6 opt append 


int inet6 opt append(void *extbuf, socklen t extlen, int offset, 
uint8 t type, socklen t len, uint t align, 
void **databufp); 


Offset should be the length returned by inet6 opt init() or a 
previous inet6 opt append(). This function returns the updated total 
length taking into account adding an option with length ’len’ and 
alignment ”align”. If extbuf is not NULL then, in addition to 
returning the length, the function inserts any needed pad option, 
initializes the option (setting the type and length fields) and 
returns a pointer to the location for the option content in databufp. 
If the option does not fit in the extension header buffer the 
function returns -1. 


Type is the 8-bit option type. Len is the length of the option data 
(i.e., excluding the option type and option length fields). 


Once inet6_opt_append() has been called the application can use the 
databuf directly, or use inet6_opt_set_val() to specify the content 
of the option. 


The option type must have a value from 2 to 255, inclusive. (0 and 1 
are reserved for the Padl and PadN options, respectively.) 


The option data length must have a value between 0 and 255, 
inclusive, and is the length of the option data that follows. 


The align parameter must have a value of 1, 2, 4, or 8. The align 
value can not exceed the value of len. 
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3. inet6 opt finish 
int inet6 opt finish(void *extbuf, socklen 七 extlen, int offset); 


Offset should be the length returned by inet6 opt init() or 
inet6 opt append(). This function returns the updated total length 
taking into account the final padding of the extension header to make 
it a multiple of 8 bytes. If extbuf is not NULL the function also 
initializes the option by inserting a Padl or PadN option of the 
proper length. 


If the necessary pad does not fit in the extension header buffer the 
function returns -1. 


4. inet6_opt_set_val 


int inet6_opt_set_val(void *databuf, int offset, void *val, 
socklen t vallen); 


Databuf should be a pointer returned by ineté6 opt append(). This 
function inserts data items of various sizes in the data portion of 
the option. Val should point to the data to be inserted. Offset 
specifies where in the data portion of the option the value should be 
inserted; the first byte after the option type and length is accessed 
by specifying an offset of zero. 


The caller should ensure that each field is aligned on its natural 
boundaries as described in Appendix B of [RFC-2460], but the function 
must not rely on the caller’s behavior. Even when the alignment 
requirement is not satisfied, inet6_opt_set_val should just copy the 
data as required. 


The function returns the offset for the next field (i.e., offset + 
vallen) which can be used when composing option content with multiple 
fields. 


5. inet6_opt_next 


int inet6_opt_next (void *extbuf, socklen_t extlen, int offset, 
uint8_t *typep, socklen_t *lenp, 
void **databufp) ; 


This function parses received option extension headers returning the 
next option. Extbuf and extlen specifies the extension header. 
Offset should either be zero (for the first option) or the length 
returned by a previous call to inet6_opt_next() or inet6_opt_find(). 
It specifies the position where to continue scanning the extension 
buffer. The next option is returned by updating typep, lenp, and 
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databufp. Typep stores the option type, lenp stores the length of 
the option data (i.e., excluding the option type and option length 
fields), and databufp points the data field of the option. This 
function returns the updated "previous" length computed by advancing 
past the option that was returned. This returned "previous" length 
can then be passed to subsequent calls to inet6 opt next(). This 
function does not return any PAD1 or PADN options. When there are no 
more options or if the option extension header is malformed the 
return value is -1. 


6. inet6 opt find 


int inet6 opt find(void *extbuf, socklen t extlen, int offset, 
uint8 t type, socklen t *lenp, 
void **databufp); 


This function is similar to the previously described inet6 opt next () 
function, except this function lets the caller specify the option 
type to be searched for, instead of always returning the next option 
in the extension header. 


If an option of the specified type is located, the function returns 
the updated "previous" total length computed by advancing past the 
option that was returned and past any options that didn’t match the 
type. This returned "previous" length can then be passed to 
subsequent calls to inet6 opt find() for finding the next occurrence 
of the same option type. 


If an option of the specified type is not located, the return value 
is -1. If the option extension header is malformed, the return value 
is 1, 


7. <inet6_opt_get_val 


int inet6_opt_get_val(void *databuf, int offset, void *val, 
socklen t vallen); 


Databuf should be a pointer returned by inet6 opt next() or 
inet6 opt find(). This function extracts data items of various sizes 
in the data portion of the option. Val should point to the 
destination for the extracted data. Offset specifies from where in 
the data portion of the option the value should be extracted; the 
first byte after the option type and length is accessed by specifying 
an offset of zero. 


It is expected that each field is aligned on its natural boundaries 
as described in Appendix B of [RFC-2460], but the function must not 
rely on the alignment. 
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The function returns the offset for the next field (i.e., offset + 
vallen) which can be used when extracting option content with 
multiple fields. 


Additional Advanced API Functions 
1. Sending with the Minimum MTU 


Unicast applications should usually let the kernel perform path MTU 
discovery [RFC-1981], as long as the kernel supports it, and should 
not care about the path MTU. Some applications, however, might not 
want to incur the overhead of path MTU discovery, especially if the 
applications only send a single datagram to a destination. A 
potential example is a DNS server. 


[RFC-1981] describes how path MTU discovery works for multicast 
destinations. From practice in using IPv4 multicast, however, many 
careless applications that send large multicast packets on the wire 
have caused implosion of ICMPv4 error messages. The situation can be 
worse when there is a filtering node that blocks the ICMPv4 messages. 
Though the filtering issue applies to unicast as well, the impact is 
much larger in the multicast cases. 


Thus, applications sending multicast traffic should explicitly enable 
path MTU discovery only when they understand that the benefit of 
possibly larger MTU usage outweighs the possible impact of MTU 
discovery for active sources across the delivery tree(s). This 
default behavior is based on the today’s practice with IPv4 multicast 
and path MTU discovery. The behavior may change in the future once 
it is found that path MTU discovery effectively works with actual 
multicast applications and network configurations. 


This specification defines a mechanism to avoid path MTU discovery by 
sending at the minimum IPv6 MTU [RFC-2460]. If the packet is larger 
than the minimum MTU and this feature has been enabled the IP layer 
will fragment to the minimum MTU. To control the policy about path 
MTU discovery, applications can use the IPV6_USE_MIN_MTU socket 
option. 


As described above, the default policy should depend on whether the 
destination is unicast or multicast. For unicast destinations path 
MTU discovery should be performed by default. For multicast 
destinations path MTU discovery should be disabled by default. This 
option thus takes the following three types of integer arguments: 


-1: perform path MTU discovery for unicast destinations but do not 
perform it for multicast destinations. Packets to multicast 
destinations are therefore sent with the minimum MTU. 
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0: always perform path MTU discovery. 


1: always disable path MTU discovery and send packets at the minimum 
MTU. 


The default value of this option is -1. Values other than -1, 0, and 
1 are invalid, and an error EINVAL will be returned for those values. 


As an example, if a unicast application intentionally wants to 
disable path MTU discovery, it will add the following lines: 


int on = 1; 
setsockopt (fd, IPPROTO IPV6, IPV6 USE MIN MTU, &on, sizeof(on)); 


Note that this API intentionally excludes the case where the 
application wants to perform path MTU discovery for multicast but to 
disable it for unicast. This is because such usage is not feasible 
considering a scale of performance issues around whether to do path 
MTU discovery or not. When path MTU discovery makes sense to a 
destination but not to a different destination, regardless of whether 
the destination is unicast or multicast, applications either need to 
toggle the option between sending such packets on the same socket, or 
use different sockets for the two classes of destinations. 


This option can also be sent as ancillary data. In the cmsghdr 

structure containing this ancillary data, the cmsg level member will 
be IPPROTO IPV6, the cmsg type member will be IPV6 USE MIN MTU, and 
the first byte of cmsg_data[] will be the first byte of the integer. 


.2. Sending without Fragmentation 


In order to provide for easy porting of existing UDP and raw socket 
applications IPv6é implementations will, when originating packets, 
automatically insert a fragment header in the packet if the packet is 
too big for the path MTU. 


Some applications might not want this behavior. An example is 
traceroute which might want to discover the actual path MTU. 


This specification defines a mechanism to turn off the automatic 
inserting of a fragment header for UDP and raw sockets. This can be 
enabled using the IPV6_DONTFRAG socket option. 


int on = 1; 
setsockopt (fd, IPPROTO_IPV6, IPV6_DONTFRAG, &o0n, sizeof(on)); 
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By default, this socket option is disabled. Setting the value to 0 
also disables the option i.e., reverts to the default behavior of 
automatic inserting. This option can also be sent as ancillary data. 
In the cmsghdr structure containing this ancillary data, the 
cmsg_level member will be IPPROTO IPV6, the cmsg_type member will be 
IPV6_DONTFRAG, and the first byte of cmsg_data[] will be the first 
byte of the integer. This API only specifies the use of this option 
for UDP and raw sockets, and does not define the usage for TCP 
sockets. 


When the data size is larger than the MTU of the outgoing interface, 
the packet will be discarded. Applications can know the result by 
enabling the IPV6_RECVPATHMTU option described below and receiving 
the corresponding ancillary data items. An additional error EMSGSIZE 
may also be returned in some implementations. Note, however, that 
some other implementations might not be able to return this 
additional error when sending a message. 


3. Path MTU Discovery and UDP 


UDP and raw socket applications need to be able to determine the 
"maximum send transport-message size" (Section 5.1 of [RFC-1981]) to 
a given destination so that those applications can participate in 
path MTU discovery. This lets those applications send smaller 
datagrams to the destination, avoiding fragmentation. 


This is accomplished using a new ancillary data item (IPV6 PATHMTU) 
which is delivered to recvmsg() without any actual data. The 
application can enable the receipt of IPV6_PATHMTU ancillary data 
items by setting the IPV6_RECVPATHMTU socket option. 


int on = 1; 
setsockopt (fd, IPPROTO_IPV6, IPV6_RECVPATHMTU, &on, sizeof (on)); 


By default, this socket option is disabled. Setting the value to 0 
also disables the option. This API only specifies the use of this 
option for UDP and raw sockets, and does not define the usage for TCP 
sockets. 


When the application is sending packets too big for the path MTU 
recvmsg() will return zero (indicating no data) but there will be a 
cmsghdr with cmsg_type set to IPV6_PATHMTU, and cmsg_len will 
indicate that cmsg_data is sizeof(struct ip6_mtuinfo) bytes long. 
This can happen when the sending node receives a corresponding ICMPv6 
packet too big error, or when the packet is sent from a socket with 
the IPV6_DONTFRAG option being on and the packet size is larger than 
the MTU of the outgoing interface. This indication is considered as 
an ancillary data item for a separate (empty) message. Thus, when 
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there are buffered messages (i.e., messages that the application has 
not received yet) on the socket the application will first receive 
the buffered messages and then receive the indication. 


The first byte of cmsg_data[] will point to a struct ip6 mtuinfo 
carrying the path MTU to use together with the IPv6 destination 
address. 


struct ip6_mtuinfo { 
struct sockaddr in6 ip6m_addr; /* dst address including 
zone ID */ 
uint32_t ip6m mtu; /* path MTU in host byte order */ 
}; 


This cmsghdr will be passed to every socket that sets the 
IPV6_RECVPATHMTU socket option, even if the socket is non-connected. 
Note that this also means an application that sets the option may 
receive an IPV6_MTU ancillary data item for each ICMP too big error 
the node receives, including such ICMP errors caused by other 
applications on the node. Thus, an application that wants to perform 
the path MTU discovery by itself needs to keep history of 
destinations that it has actually sent to and to compare the address 
returned in the ip6 mtuinfo structure to the history. An 
implementation may choose not to delivery data to a connected socket 
that has a foreign address that is different than the address 
specified in the ip6m_addr structure. 


When an application sends a packet with a routing header, the final 
destination stored in the ip6m addr member does not necessarily 
contain complete information of the entire path. 


4. Determining the Current Path MTU 


Some applications might need to determine the current path MTU e.g., 
applications using IPV6_RECVPATHMTU might want to pick a good 
starting value. 


This specification defines a get-only socket option to retrieve the 
current path MTU value for the destination of a given connected 
socket. If the IP layer does not have a cached path MTU value it 
will return the interface MTU for the interface that will be used 
when sending to the destination address. 


This information is retrieved using the IPV6_PATHMTU socket option. 
This option takes a pointer to the ip6_mtuinfo structure as the 
fourth argument, and the size of the structure should be passed as a 
value-result parameter in the fifth argument. 
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struct ip6 mtuinfo mtuinfo; 
socklen t infolen = sizeof (mtuinfo); 


getsockopt (fd, IPPROTO IPV6, IPV6 PATHMTU, &mtuinfo, &infolen); 


When the call succeeds, the path MTU value is stored in the ip6m mtu 
member of the ip6 mtuinfo structure. Since the socket is connected, 
the ipém addr member is meaningless and should not be referred to by 
the application. 


This option can only be used for a connected socket, because a non- 
connected socket does not have the information of the destination and 


there is no way to pass the destination via getsockopt(). When 
getsockopt() for this option is issued on a non-connected socket, the 
call will fail. Despite this limitation, this option is still useful 


from a practical point of view, because applications that care about 
the path MTU tend to send a lot of packets to a single destination 
and to connect the socket to the destination for performance reasons. 
If the application needs to get the MTU value in a more generic way, 
it should use a more generic interface, such as routing sockets 
[TCPIPILLUST]. 


Ordering of Ancillary Data and IPv6 Extension Headers 


Three IPv6 extension headers can be specified by the application and 
returned to the application using ancillary data with sendmsg() and 
recvmsg(): the Routing header, Hop-by-Hop options header, and 
Destination options header. When multiple ancillary data objects are 
transferred via recvmsg() and these objects represent any of these 
three extension headers, their placement in the control buffer is 
directly tied to their location in the corresponding IPv6 datagram. 
For example, when the application has enabled the IPV6_RECVRTHDR and 
IPV6_RECVDSTOPTS options and later receives an IPv6 packet with 
extension headers in the following order: 


The IPv6 header 

A Hop-by-Hop options header 

A Destination options header (1) 
A Routing header 

An Authentication header 

A Destination options header (2) 
A UDP header and UDP data 
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then the application will receive three ancillary data objects in the 
following order: 


an object with cmsg type set to IPV6 DSTOPTS, which represents 

the destination options header (1) 

an object with cmsg type set to IPV6 RTHDR, which represents the 
Routing header 

an object with cmsg type set to IPV6 DSTOPTS, which represents the 
destination options header (2) 


This example follows the header ordering described in [RFC-2460], but 
the receiving side of this specification does not assume the 
ordering. Applications may receive any numbers of objects in any 
order according to the ordering of the received IPv6 datagram. 


For the sending side, however, this API imposes some ordering 
constraints according to [RFC-2460]. Applications using this API 
cannot make a packet with extension headers that do not follow the 
ordering. Note, however, that this does not mean applications must 
always follow the restriction. This is just a limitation in this API 
in order to give application programmers a guideline to construct 
headers in a practical manner. Should an application need to make an 
outgoing packet in an arbitrary order about the extension headers, 
some other technique, such as the datalink interfaces BPF or DLPI, 
must be used. 


The followings are more details about the constraints: 


- Each IPV6 xxx ancillary data object for a particular type of 
extension header can be specified at most once in a single control 
buffer. 


- IPV6_xxx ancillary data objects can appear in any order ina 
control buffer, because there is no ambiguity of the ordering. 


- Each set of IPV6 xxx ancillary data objects and sticky options 
will be put in the outgoing packet along with the header ordering 
described in [RFC-2460]. 


- An ancillary data object or a sticky option of IPV6 RTHDRDSTOPTS 
will affect the outgoing packet only when a Routing header is 
specified as an ancillary data object or a sticky option. 
Otherwise, the specified value for IPV6 RTHDRDSTOPTS will be 
ignored. 


Stevens, et al. Informational [Page 49] 


RFC 3542 Advanced Sockets API for IPv6 May 2003 


13:; 


For example, when an application sends a UDP datagram with a control 
data buffer containing ancillary data objects in the following order: 


an object with cmsg_type set to IPV6_DSTOPTS 
an object with cmsg_type set to IPV6_RTHDRDSTOPTS 
an object with cmsg_type set to IPV6_HOPOPTS 


and the sending socket does not have any sticky options, then the 
outgoing packet would be constructed as follows: 


The IPv6 header 

A Hop-by-Hop options header 
A Destination options header 
A UDP header and UDP data 


where the destination options header corresponds to the ancillary 
data object with the type IPV6 DSTOPTS. 


Note that the constraints above do not necessarily mean that the 
outgoing packet sent on the wire always follows the header ordering 
specified in this API document. The kernel may insert additional 
headers that break the ordering as a result. For example, if the 
kernel supports Mobile IPv6, an additional destination options header 
may be inserted before an authentication header, even without a 
routing header. 


This API does not provide access to any other extension headers than 
the supported three types of headers. In particular, no information 
is provided about the IP security headers on an incoming packet, nor 
can be specified for an outgoing packet. This API is for 
applications that do not care about the existence of IP security 
headers. 


IPv6-Specific Options with IPv4-Mapped IPv6 Addresses 


The various socket options and ancillary data specifications defined 
in this document apply only to true IPv6 sockets. It is possible to 
create an IPv6 socket that actually sends and receives IPv4 packets, 
using IPv4-mapped IPv6 addresses, but the mapping of the options 
defined in this document to an IPv4 datagram is beyond the scope of 
this document. 


In general, attempting to specify an IPv6-only option, such as the 
Hop-by-Hop options, Destination options, or Routing header on an IPv6 
socket that is using IPv4-mapped IPv6 addresses, will probably result 
in an error. Some implementations, however, may provide access to 
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the packet information (source/destination address, send/receive 
interface, and hop limit) on an IPv6 socket that is using IPv4-mapped 
IPv6 addresses. 


Extended interfaces for rresvport, rcmd and rexec 


Library functions that support the "r" commands hide the creation of 
a socket and the name resolution procedure from an application. When 
the libraries return an AF INET6 socket to an application that do not 
support the address family, the application may encounter an 
unexpected result when, e.g., calling getpeername() for the socket. 
In order to support AF INET6 sockets for the "r" commands while 
keeping backward compatibility, this section defines some extensions 
to the libraries. 


1. rresvport af 


The rresvport() function is used by the rcmd() function, and this 
function is in turn called by many of the "r" commands such as 
rlogin. While new applications are not being written to use the 
remd() function, legacy applications such as rlogin will continue to 
use it and these will be ported to IPv6. 


rresvport() creates an IPv4/TCP socket and binds a "reserved port" to 
the socket. Instead of defining an IPv6 version of this function we 
define a new function that takes an address family as its argument. 


#include <unistd.h> 
int rresvport af(int *port, int family); 


This function behaves the same as the existing rresvport() function, 
but instead of creating an AF INET TCP socket, it can also create an 
AF INET6 TCP socket. The family argument is either AF INET or 

AF INET6, and a new error return is EAFNOSUPPORT if the address 
family is not supported. 


(Note: There is little consensus on which header defines the 
rresvport() and rcmd() function prototypes. 4.4BSD defines it in 
<unistd.h>, others in <netdb.h>, and others don’t define the function 
prototypes at all.) 


.2. emd af 


The existing remd() function can not transparently use AF_INET6 
sockets since an application would not be prepared to handle AF_INET6 
addresses returned by e.g., getpeername() on the file descriptor 
created by rcmd(). Thus a new function is needed. 
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int rcmd_af (char **ahost, unsigned short rport, 
const char *locuser, const char *remuser, 
const char *cmd, int *fd2p, int af) 


This function behaves the same as the existing rcmd() function, but 
instead of creating an AF INET TCP socket, it can also create an 

AF INET6 TCP socket. The family argument is AF INET, AF INET6, or 

AF UNSPEC. When either AF INET or AF INET6 is specified, this 
function will create a socket of the specified address family. When 
AF_UNSPEC is specified, it will try all possible address families 
until a connection can be established, and will return the associated 
socket of the connection. A new error EAFNOSUPPORT will be returned 
if the address family is not supported. 


3. rexec af 


The existing rexec() function can not transparently use AF INET6 
sockets since an application would not be prepared to handle AF INET6 
addresses returned by e.g., getpeername() on the file descriptor 
created by rexec(). Thus a new function is needed. 


int rexec_af(char **ahost, unsigned short rport, const char *name, 
const char *pass, const char *cmd, int *fd2p, int af) 


This function behaves the same as the existing rexec() function, but 
instead of creating an AF_INET TCP socket, it can also create an 
AF_INET6 TCP socket. The family argument is AF_INET, AF_INET6, or 
AF_UNSPEC. When either AF_INET or AF_INET6 is specified, this 
function will create a socket of the specified address family. When 
AF_UNSPEC is specified, it will try all possible address families 
until a connection can be established, and will return the associated 
socket of the connection. A new error EAFNOSUPPORT will be returned 
if the address family is not supported. 


Summary of New Definitions 


The following list summarizes the constants and structure, 
definitions discussed in this memo, sorted by header. 


<netinet/icmp6.h> ICMP6_DST_UNREACH 
<netinet/icmp6.h> ICMP6_DST_UNREACH_ADDR 
<netinet/icmp6.h> ICMP6_DST_UNREACH_ADMIN 
<netinet/icmp6.h> ICMP6_DST_UNREACH_BEYONDSCOPE 
<netinet/icmp6.h> ICMP6_DST_UNREACH_NOPORT 
<netinet/icmp6.h> ICMP6_DST_UNREACH_NOROUTE 
<netinet/icmp6.h> ICMP6_ECHO_REPLY 
<netinet/icmp6.h> ICMP6_ECHO_REQUEST 
<netinet/icmp6.h> ICMP6_INFOMSG_MASK 
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<netinet/icmp6.h> ICMP6 PACKET TOO BIG 
<netinet/icmp6.h> ICMP6 PARAMPROB HEADER 
<netinet/icmp6.h> ICMP6 PARAMPROB NEXTHEADER 
<netinet/icmp6.h> ICMP6 PARAMPROB OPTION 
<netinet/icmp6.h> ICMP6 PARAM PROB 
<netinet/icmp6.h> ICMP6 ROUTER RENUMBERING 
<netinet/icmp6.h> ICMP6 RR FLAGS FORCEAPPLY 
<netinet/icmp6.h> ICMP6 RR FLAGS PREVDONE 
<netinet/icmp6.h> ICMP6 RR FLAGS REQRESULT 
<netinet/icmp6.h> ICMP6 RR FLAGS SPECSITE 
<netinet/icmp6.h> ICMP6 RR FLAGS TEST 
<netinet/icmp6.h> ICMP6 RR PCOUSE FLAGS DECRPLTIME 
<netinet/icmp6.h> ICMP6 RR PCOUSE FLAGS DECRVLTIME 
<netinet/icmp6.h> ICMP6 RR PCOUSE RAFLAGS AUTO 
<netinet/icmp6.h> ICMP6 RR PCOUSE RAFLAGS ONLINK 
<netinet/icmp6.h> ICMP6 RR RESULT FLAGS FORBIDDEN 
<netinet/icmp6.h> ICMP6 RR RESULT FLAGS 00B 
<netinet/icmp6.h> ICMP6 TIME EXCEEDED 
<netinet/icmp6.h> ICMP6 TIME EXCEED REASSEMBLY 
<netinet/icmp6.h> ICMP6 TIME EXCEED TRANSIT 
<netinet/icmp6.h> MLD LISTENER QUERY 
<netinet/icmp6.h> MLD LISTENER REDUCTION 
<netinet/icmp6.h> MLD LISTENER REPORT 
<netinet/icmp6.h> ND NA FLAG OVERRIDE 
<netinet/icmp6.h> ND NA FLAG ROUTER 
<netinet/icmp6.h> ND NA FLAG SOLICITED 
<netinet/icmp6.h> ND NEIGHBOR ADVERT 
<netinet/icmp6.h> ND NEIGHBOR SOLICIT 
<netinet/icmp6.h> ND OPT MTU 

<netinet/icmp6.h> ND OPT PI FLAG AUTO 
<netinet/icmp6.h> ND OPT PI FLAG ONLINK 
<netinet/icmp6.h> ND OPT PREFIX INFORMATION 
<netinet/icmp6.h> ND OPT REDIRECTED HEADER 
<netinet/icmp6.h> ND OPT SOURCE LINKADDR 
<netinet/icmp6.h> ND OPT TARGET LINKADDR 
<netinet/icmp6.h> ND RA FLAG MANAGED 
<netinet/icmp6.h> ND RA FLAG OTHER 
<netinet/icmp6.h> ND REDIRECT 

<netinet/icmp6.h> ND ROUTER ADVERT 
<netinet/icmp6.h> ND ROUTER SOLICIT 


222222222222z222=2z202ar 


<netinet/icmp6.h> struct icmp6_filter{}; 
<netinet/icmp6.h> struct icmp6_hdr{}; 
<netinet/icmp6.h> struct icmp6 router renum(); 
<netinet/icmp6.h> struct mld hdr(); 
<netinet/icmp6.h> struct nd neighbor advert(); 
<netinet/icmp6.h> struct nd neighbor solicit(); 
<netinet/icmp6.h> struct nd opt hadr(); 
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h> 
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h> 
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h> 
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struct 
struct 
struct 
struct 
struct 
struct 
struct 
struct 
struct 


nd_opt_mtu{}; 

nd opt prefix infot); 
nd opt rd hdrt); 

nd redirect(); 

nd router adverti); 
nd router solicit(); 
rr_pco_match{}; 
rr_pco_use{}; 
rr_result{}; 


IPPROTO_AH 
IPPROTO_DSTOPTS 
IPPROTO_ESP 
IPPROTO_FRAGMENT 
IPPROTO_HOPOPTS 
IPPROTO_ICMPV6 
IPPROTO_IPV6 
IPPROTO_NONE 
IPPROTO_ROUTING 
IPV6_CHECKSUM 
IPV6_DONTFRAG 
IPV6_DSTOPTS 
IPV6_HOPLIMIT 
IPV6_HOPOPTS 


IPV6_NEXTHOP 
IPV6_PATHMTU 
IPV6_PKTINFO 
IPV6_RECVDSTOPTS 
IPV6_RECVHOPLIMIT 
IPV6_RECVHOPOPTS 
IPV6_RECVPKTINFO 
IPV6_RECVRTHDR 
IPV6_RECVTCLASS 
IPV6_RTHDR 
IPV6_RTHDRDSTOPTS 
IPV6 RTHDR TYPE 0 
IPV6 RECVPATHMTU 
IPV6 TCLASS 

IPV6 USE MIN MTU 
struct in6_pktinfo{}; 
struct ip6_mtuinfo{}; 


IP6F_MORE_FRAG 
IP6F_OFF_MASK 
IP6F_RESERVED_MASK 
IP60PT_JUMBO 
IP60PT_JUMBO_LEN 
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IP60PT_MUTABLE 
IP60PT_NSAP_ADDR 
IP60PT_PAD1 

IP6OPT PADN 

IP6O0PT ROUTER ALERT 
IP6OPT TUNNEL LIMIT 
IP6OPT TYPE DISCARD 
IP6OPT TYPE FORCEICMP 
IP6OPT TYPE ICMP 

IP6OPT TYPE SKIP 

IP6 ALERT AN 

IP6 ALERT MLD 

IP6 ALERT RSVP 

struct ip6_dest{}; 
struct ipé_frag{}; 
struct ip6_hbh{}; 
struct ip6_hdr{}; 
struct ipé6_opt{}; 
struct ip6_opt_jumbo{}; 
struct ip6_opt_nsap{}; 
struct ip6_opt_router{}; 
struct ip6_opt_tunnel{}; 
struct ip6_rthdr{}; 
struct ip6_rthdr0{}; 


The following list summarizes the function and macro prototypes 


discussed in this memo, 


<netinet/icmp6. 
<netinet/icmp6. 


<netinet/icmp6. 


<netinet/icmp6. 
<netinet/icmp6. 


<netinet/icmp6. 


<netinet/in.h> 


<netinet/in.h> 
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h> 


h> 


h> 


sorted by header. 


void ICMP6 FILTER SETBLOCK (int, struct 

icmp6 filter *); 
void 
ICMP6 FILTER SETBLOCKALL(struct icmpé6 filter *); 
void 
ICMP6 FILTER SETPASS (int, 

struct icmp6 filter *); 

void 
ICMP6 FILTER SETPASSALL(struct icmp6 filter *); 


int ICMP6 FILTER WILLBLOCK (int, 
const struct icmp6 filter *); 
int ICMP6 FILTER WILLPASS (int, 


const struct icmp6 filter *); 


int IN6 ARE ADDR EQUAL (const struct in6 addr *, 
const struct in6 addr *); 


int, 
uint_t, 


int inet6_opt_append(void *, 
uint8_t, 
void **); 


socklen_t, 
socklen_t, 
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<sys/socket. 
<sys/socket. 
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int 


int 
int 
int 


int 


int 


void *inet6 rth init(void *, 


int inet6_rth_reverse(const void *, 


inet6 opt get val(void *, 


inet6 opt find(void *, 


inet6 opt finish(void *, 
inet6 opt init(void *, 
inet6 opt next (void *, 


inet6 opt set val(void *, 


int, 
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void *, 


socklen t); 


int, uint8 t 
socklen t *, 


socklen t, 
socklen t); 
socklen 七 ， 


socklen 七 ， 


r 
void **); 
int); 


int, uint8 t *, 
socklen t *, void **); 
int, 


void *, 


inet6 rth add(void *, 
const struct in6 addr *); 
struct in6 addr inet6_rth_getaddr (const 


int, int); 


socklen t); 


void *, 
int); 


socklen t, 


void *); 


int ineté6 rth segments(const void *); 
soccklen t inet6 rth space(int, 


int 


socklen t CMSG L 


int rresvport af(int *, 
int rcmd_af (char **, 
const char *, 
const char *, 
int rexec af(char **, 
const char *, 
const char *, 


Security Considerations 


et al. 


IP6OPT TYPE (uint8 t); 


EN(socklen t); 
socklen t CMSG SPACE (socklen t); 


int); 


const 


ant *; 
unsigned short, 

const char *, 
int: *, 


int); 


unsigned short, 


char *, 
int); 


int); 


The setting of certain Hop-by-Hop options and Destination options may 
be restricted to privileged processes. 


Similarly some Hop-by-Hop 


options and Destination options may not be returned to non-privileged 
applications. 


The ability to specify an arbitrary source address using IPV6 PKTINFO 
must be prevented; 


at least for non-privileged processes. 
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17. Changes from RFC 2292 
Significant changes that affect the compatibility to RFC 2292: 


- Removed the IPV6 PKTOPTIONS socket option by allowing sticky 
options to be set with individual setsockopt() calls. 


- Removed the ability to be able to specify Hop-by-Hop and 
Destination options using multiple ancillary data items. The 
application, using the inet6 opt xxx() routines (see below), is 
responsible for formatting the whole extension header. 


- Removed the support for the loose/strict Routing header since that 
has been removed from the IPv6 specification. 


- Loosened the constraints for jumbo payload option that this option 
was always hidden from applications. 


- Disabled the use of the IPV6_HOPLIMIT sticky option. 
- Removed ip6r0 addr field from the ip6_rthdr structure. 


- Intentionally unspecified how to get received packet’s information 
on TCP sockets. 


New features: 


- Added IPV6 RTHDRDSTOPTS to specify a Destination Options header 
before the Routing header. 


- Added separate IPV6_RECVxxx options to enable the receipt of the 
corresponding ancillary data items. 


- Added inet6_rth_xxx() and inet6_opt_xxx() functions to deal with 
routing or IPv6 options headers. 


- Added extensions of libraries for the "r" commands. 

- Introduced additional IPv6 option definitions such as IP6OPT_PAD1. 
- Added MLD and router renumbering definitions. 

- Added MTU-related socket options and ancillary data items. 


- Added options and ancillary data items to manipulate the traffic 
class field. 
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- Changed the name of ICMPv6 unreachable code 2 to be "beyond scope 
of source address."  ICMP6 DST UNREACH NOTNEIGHBOR was removed 
with this change. 


Clarifications: 

- Added clarifications on extension headers ordering; for the 
sending side, assume the recommended ordering described in RFC 
2460. For the receiving side, do not assume any ordering and pass 
all headers to the application in the received order. 


- Added a summary about the interface selection rule. 


- Clarified the ordering between IPV6 MULTICAST IF and the 
IPV6 PKTINFO sticky option for multicast packets. 


- Clarified how sticky options and the ICMPv6 filter are turned off 
and that getsockopt() of a sticky option returns what was set with 
setsockopt (). 

- Clarified that IPV6 NEXTHOP should be ignored for a multicast 
destination, that it should not contradict with the specified 
outgoing interface, and that the next hop should be a sockaddr in6 
structure. 

- Clarified corner cases of IPV6_CHECKSUM. 

- Aligned with the POSIX standard. 

Editorial changes: 


- Replaced MUST with must (since this is an informational document). 


- Revised abstract to be more clear and concise, particularly 
concentrating on differences from RFC 2292. 


- Made the URL of assigned numbers less specific so that it would be 
more robust for future changes. 


- Updated the reference to the basic API. 
- Added a reference to the latest POSIX standard. 


- Moved general specifications of ancillary data and CMSG macros to 
the appendix. 
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Appendix A: Ancillary Data Overview 


4.2BSD allowed file descriptors to be transferred between separate 
processes across a UNIX domain socket using the sendmsg() and 
recvmsg() functions. Two members of the msghdr structure, 

msg accrights and msg accrightslen, were used to send and receive the 
descriptors. When the OSI protocols were added to 4.3BSD Reno in 
1990 the names of these two fields in the msghdr structure were 
changed to msg control and msg controllen, because they were used by 
the OSI protocols for "control information", although the comments in 
the source code call this "ancillary data". 


Other than the OSI protocols, the use of ancillary data has been 
rare. In 4.4BSD, for example, the only use of ancillary data with 
IPv4 is to return the destination address of a received UDP datagram 
if the IP RECVDSTADDR socket option is set. With Unix domain sockets 
ancillary data is still used to send and receive descriptors. 


Nevertheless the ancillary data fields of the msghdr structure 
provide a clean way to pass information in addition to the data that 
is being read or written. The inclusion of the msg control and 

msg controllen members of the msghdr structure along with the cmsghdr 
structure that is pointed to by the msg control member is required by 
the Posix sockets API standard. 


1. The msghdr Structure 


The msghdr structure is used by the recvmsg() and sendmsg() 
functions. Its Posix definition is: 


struct msghdr { 


void *msg_name; /* ptr to socket address 
structure */ 

socklen_t msg_namelen; /* size of socket address 
structure */ 

struct iovec *msg_iov; /* scatter/gather array */ 

int msg iovlen; /* # elements in msg_iov */ 

void *msg_control; /* ancillary data */ 

socklen_t msg_controllen; /* ancillary data buffer length */ 

int msg_flags; /* flags on received message */ 


}; 
The structure is declared as a result of including <sys/socket.h>. 


(Note: Before Posix the two "void *" pointers were typically "char 
*", and the two socklen_t members were typically integers. Earlier 
drafts of Posix had the two socklen_t members as size_t, but it then 
changed these to socklen_t to simplify binary portability for 64-bit 
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implementations and to align Posix with X/Open’s Networking Services, 
Issue 5. The change in msg_control to a "void *" pointer affects any 
code that increments this pointer.) 


Most Berkeley-derived implementations limit the amount of ancillary 
data in a call to sendmsg() to no more than 108 bytes (an mbuf). 

This API requires a minimum of 10240 bytes of ancillary data, but it 
is recommended that the amount be limited only by the buffer space 
reserved by the socket (which can be modified by the SO_SNDBUF socket 
option). (Note: This magic number 10240 was picked as a value that 
should always be large enough. 108 bytes is clearly too small as the 
maximum size of a Routing header is 2048 bytes.) 


.2. The cmsghdr Structure 


The cmsghdr structure describes ancillary data objects transferred by 
recvmsg() and sendmsg(). Its Posix definition is: 


struct cmsghdr { 


socklen t cmsg len; /* #bytes, including this header */ 
int cmsg level; /* originating protocol */ 
int cmsg type; /* protocol-specific type */ 

/* followed by unsigned char cmsg_data[]; */ 


}; 
This structure is declared as a result of including <sys/socket.h>. 


(Note: Before Posix the cmsg_len member was an integer, and not a 
socklen_t. See the Note in the previous section for why socklen_t is 
used here.) 


As shown in this definition, normally there is no member with the 
name cmsg_data[]. Instead, the data portion is accessed using the 
CMSG_xxx() macros, as described in Section 20.3. Nevertheless, it is 
common to refer to the cmsg_data[] member. 


When ancillary data is sent or received, any number of ancillary data 
objects can be specified by the msg_control and msg_controllen 
members of the msghdr structure, because each object is preceded by a 
cmsghdr structure defining the object’s length (the cmsg_len member). 
Historically Berkeley-derived implementations have passed only one 
object at a time, but this API allows multiple objects to be passed 
in a single call to sendmsg() or recvmsg(). The following example 
shows two ancillary data objects in a control buffer. 
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| <--------------------------- msg:controlleén +*+>==-StystassgsraSSsansm >| 
| OR | 
Se aS ss msg :Controllén ~“ > | 

| 
|<----- ancillary data object ----- >|<---- ancillary data object ----- >| 
| <------ min CMSG SPACE () --======= >|<----- min CMSG_SPACE() --------- > | 
| | | 
| <---------- Ensgalen ==-3=-=="7> >| |<-------- CMS I 二 人 和 二 一 二 二 一 一 了 一 一 >| 
<--------- CMSG_LEN() --------- > <------- CMSG_LEN() ---------- > 
十 一 一 一 一 一 和 二 二 二 地 三 十 一 一 一 一 一 Bi pereenaSn 十 一 一 十 一 一 一 一 一 +----- tasses Sn 十 一 一 十 
|cmsg_|cmsg_|cmsg_ |xx| cmsg_ |xx|cmsg_|cmsg_|cmsg_|xx| cmsg_ |xx| 
|len |level|type |xx| data[l] |Xx|len |level|type |XX| data[] |Xx| 
Pannas +----- +----- +--4+----------- 十 一 一 十 一 一 一 一 一 +----- +----- +—=+=—======== 十 一 一 十 


msg control 
points here 


The fields shown as "XX" are possible padding, between the cmsghdr 
structure and the data, and between the data and the next cmsghdr 
structure, if required by the implementation. While sending an 
application may or may not include padding at the end of last 
ancillary data in msg controllen and implementations must accept both 
as valid. On receiving a portable application must provide space for 
padding at the end of the last ancillary data as implementations may 
copy out the padding at the end of the control message buffer and 
include it in the received msg_controllen. When recvmsg() is called 
if msg_controllen is too small for all the ancillary data items 
including any trailing padding after the last item an implementation 
may set MSG_CTRUNC. 


20.3. Ancillary Data Object Macros 
To aid in the manipulation of ancillary data objects, three macros 
from 4.4BSD are defined by Posix: CMSG_DATA(), CMSG_NXTHDR(), and 
CMSG_FIRSTHDR(). Before describing these macros, we show the 


following example of how they might be used with a call to recvmsg(). 


struct msghdr msg; 
struct cmsghdr *cmsgptr; 


/* fill in msg */ 


/* call recvmsg() */ 
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for (cmsgptr = CMSG FIRSTHDR(&msg); cmsgptr != NULL; 

cmsgptr = CMSG NXTHDR(&msg, cmsgptr)) { 

if (cmsgptr->cmsg len == 0) { 
/* Error handling */ 

break; 

) 

if (cmsgptr->cmsg level == ... && 
cmsgptr->cmsg type ==... ) { 


u_char *ptr; 


ptr = CMSG DATA (cmsgptr); 
/* process data pointed to by ptr */ 


} 


We now describe the three Posix macros, followed by two more that are 
new with this API: CMSG SPACE() and CMSG LEN(). All these macros are 
defined as a result of including <sys/socket.h>. 


ic feral CMSG_FIRSTHDR 
struct cmsghdr *CMSG_FIRSTHDR(const struct msghdr *mhdr) ; 


CMSG_FIRSTHDR() returns a pointer to the first cmsghdr structure in 
the msghdr structure pointed to by mhdr. The macro returns NULL if 
there is no ancillary data pointed to by the msghdr structure (that 
is, if either msg_control is NULL or if msg_controllen is less than 
the size of a cmsghdr structure). 


One possible implementation could be 


#define CMSG_FIRSTHDR(mhdr) \ 
( (mhdr)->msg controllen >= sizeof(struct cmsghdr) ? \ 
(struct cmsghdr *) (mhdr)->msg control : \ 
(struct cmsghdr *)NULL ) 


(Note: Most existing implementations do not test the value of 
msg_controllen, and just return the value of msg control. The value 
of msg_controllen must be tested, because if the application asks 
recvmsg() to return ancillary data, by setting msg_control to point 
to the application’s buffer and setting msg_controllen to the length 
of this buffer, the kernel indicates that no ancillary data is 
available by setting msg_controllen to 0 on return. It is also 
easier to put this test into this macro, than making the application 
perform the test.) 
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20.3.2. CMSG NXTHDR 
As described in Section 5.1, CMSG NXTHDR has been extended to handle 
a NULL 2nd argument to mean "get the first header". This provides an 


alternative way of coding the processing loop shown earlier: 


struct msghdr msg; 
struct cmsghdr *cmsgptr = NULL; 


/* fill in msg */ 


/* call recvmsg() */ 
while ((cmsgptr = CMSG NXTHDR(&msg, cmsgptr)) != NULL) ( 
if (cmsgptr->cmsg len == 0) { 
/* Error handling */ 
break; 
) 
if (cmsgptr->cmsg level == ... && 
cmsgptr->cmsg type ==... ) { 


u_char *ptr; 


ptr = CMSG_DATA(cmsgptr) ; 
/* process data pointed to by ptr */ 


} 


One possible implementation could be: 


#define CMSG_NXTHDR(mhdr, cmsg) \ 
(((cmsg) == NULL) ? CMSG_FIRSTHDR(mhdr) : \ 
(((u char *) (cmsg) + ALIGN_H((cmsg)->cmsg_len) \ 
+ ALIGN_D (sizeof (struct cmsghdr)) > \ 
(u_char *) ((mhdr)->msg control) + (mhdr)->msg controllen) ? \ 
(struct cmsghdr *)NULL : \ 
(struct cmsghdr *) ((u_char *) (cmsg) + \ 
ALIGN H((cmsg)->cmsg len)))) 


The macros ALIGN H() and ALIGN D(), which are implementation 
dependent, round their arguments up to the next even multiple of 
whatever alignment is required for the start of the cmsghdr structure 
and the data, respectively. (This is probably a multiple of 4 or 8 
bytes.) They are often the same macro in implementations platforms 
where alignment requirement for header and data is chosen to be 
identical. 
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20.3.3.  CMSG DATA 
unsigned char *CMSG_DATA(const struct cmsghdr *cmsg); 
CMSG DATA() returns a pointer to the data (what is called the 
cmsg data[] member, even though such a member is not defined in the 
structure) following a cmsghdr structure. 


One possible implementation could be: 


#define CMSG DATA(cmsg) ( (u_char *) (cmsg) + N 
ALIGN D(sizeof(struct cmsghdr)) ) 


20.3.4.  CMSG SPACE 


CMSG SPACE is new with this API (see Section 5.2). It is used to 
determine how much space needs to be allocated for an ancillary data 
item. 


One possible implementation could be: 


#define CMSG SPACE (length) ( ALIGN D(sizeof(struct cmsghdr)) + \ 
ALIGN H(length) ) 


20.3.5.  CMSG LEN 
CMSG LEN is new with this API (see Section 5.3). It returns the 
value to store in the cmsg len member of the cmsghdr structure, 
taking into account any padding needed to satisfy alignment 
requirements. 


One possible implementation could be: 


#define CMSG LEN (length) ( ALIGN D(sizeof(struct cmsghdr)) + \ 
length ) 


21. Appendix B: Examples Using the ineté6 rth XXX() Functions 


Here we show an example for both sending Routing headers and 
processing and reversing a received Routing header. 


21.1. Sending a Routing Header 
As an example of these Routing header functions defined in this 
document, we go through the function calls for the example on p. 17 


of [RFC-2460]. The source is S, the destination is D, and the three 
intermediate nodes are Il, I2, and I3. 
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src: 
dst: 

AP 
A[2]: 
SJ 
#seg: 


src andd 
header. 
header. 


The six v 
Routing h 
of setsoc 


void 
sockle 
struct 
struct 
int 
struct 


extlen 
cmsgle 
cmsgpt 
cmsgpt 
cmsgpt 
cmsgpt 


extptr = 


extptr 
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S ----- > IL ----- > I2 ----- > I3 ----- >D 
E S S S S S 
D Il I2 I3 D D 
Il 12 Il Il Il 11 
I2 T3 T3 I2 Tæ 12 
I3 D D D I3 I3 
3 3 2 1 0 3 


st are the source and destination IPv6 addresses in the IPv6 
A[1], A[2], and A[3] are the three addresses in the Routing 
#seg is the Segments Left field in the Routing header. 


alues in the column beneath node S are the values in the 
eader specified by the sending application using sendmsg() 


kopt(). The function calls by the sender would look like: 
*extptr; 
nt extlen; 


msghdr msg; 

cmsghdr *cmsgptr; 
cmsglen; 

sockaddr in6 Il, I2, 13, D; 


= ineté6 rth space(IPV6 RTHDR TYPE 0, 3); 
n = CMSG SPACE (extlen); 

r = malloc(cmsglen); 

r->cmsg len = CMSG LEN (extlen); 

r->cmsg level = IPPROTO IPV6; 

r->cmsg type = IPV6 RTHDR; 


CMSG DATA (cmsgptr); 
= inet6 rth init(extptr, extlen, IPV6 RTHDR TYPE 0, 3); 


inet6 rth add(extptr, &Il.siné6 addr); 
inet6 rth add(extptr, &I2.sin6 addr); 
inet6 rth add(extptr, &13.sin6_addr) ; 


msg.ms 
msg.ms 


/* fin 
/* cal 


We also a 
specified 


Stevens, et 


g control = cmsgptr; 
g controllen = cmsglen; 


ish filling in msg(), msg name = D */ 
1 sendmsg() */ 


ssume that the source address for the socket is not 
(i.e., the asterisk in the figure). 
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The four columns of six values that are then shown between the five 
nodes are the values of the fields in the packet while the packet is 
in transit between the two nodes. Notice that before the packet is 
sent by the source node S, the source address is chosen (replacing 
the asterisk), Il becomes the destination address of the datagram, 
the two addresses A[2] and A[3] are "shifted up", and D is moved to 
A[3]. 


The columns of values that are shown beneath the destination node are 
the values returned by recvmsg(), assuming the application has 
enabled both the IPV6 RECVPKTINFO and IPV6 RECVRTHDR socket options. 
The source address is S (contained in the sockaddr in6 structure 
pointed to by the msg name member), the destination address is D 
(returned as an ancillary data object in an in6 pktinfo structure), 
and the ancillary data object specifying the Routing header will 
contain three addresses (Il, 12, and 13). The number of segments in 
the Routing header is known from the Hdr Ext Len field in the Routing 
header (a value of 6, indicating 3 addresses). 


The return value from inet6 rth segments() will be 3 and 
inet6 rth getaddr(0) will return Il, inet6 rth getaddr(1l) will return 
I2, and ineté6 rth getaddr(2) will return I3, 


If the receiving application then calls inet6 rth reverse(), the 
order of the three addresses will become 13, I2, and I1. 


We can also show what an implementation might store in the ancillary 
data object as the Routing header is being built by the sending 
process. If we assume a 32-bit architecture where sizeof (struct 
cmsghdr) equals 12, with a desired alignment of 4-byte boundaries, 
then the call to inet6 rth space(3) returns 68: 12 bytes for the 
cmsghdr structure and 56 bytes for the Routing header (8 + 3*16). 


The call to inet6_rth_init() initializes the ancillary data object to 
contain a Type 0 Routing header: 


十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg_len = 20 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg_level = IPPROTO_IPV6 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg type = IPV6 RTHDR | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 


| Next Header | Hdr Ext Len=6 | Routing Type=0 | Seg Left=0 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| Reserved | 


十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
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The first call to inet6_rth_add() adds Il to the list. 


十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg_len = 36 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg_level = IPPROTO_IPV6 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg type = IPV6 RTHDR | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| Next Header | Hdr Ext Len=6 | Routing Type=0 | Seg Left=1 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| Reserved | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
+ + 
十 Address[1] = I1 + 
+ + 
十 一 十 


十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


cmsg len is incremented by 16, and the Segments Left field is 
incremented by 1. 
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The next call to inet6_rth_add() adds I2 to the list. 


十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg_len = 52 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg_level = IPPROTO_IPV6 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
cmsg type = IPV6 RTHDR 
一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 
Next Header | Hdr Ext Len=6 | Routing Type=0 | Seg Left=2 
一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 
Reserved 
一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


Address[1] = I1 


一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


Address[2] = 12 


二 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 
二 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


cmsg_len is incremented by 16, and the Segments Left field is 
incremented by 1. 
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The last call to inet6_rth_add() adds I3 to the list. 


十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg_len = 68 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
| cmsg_level = IPPROTO_IPV6 | 
十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 
cmsg type = IPV6 RTHDR 
一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 
Next Header | Hdr Ext Len=6 | Routing Type=0 | Seg Left=3 
一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 
Reserved 
一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


Address[1] = I1 


一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


Address[2] = 12 


一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


Address[3] = I3 


二 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 
二 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 十 一 


cmsg_len is incremented by 16, and the Segments Left field is 
incremented by 1. 


21.2. Receiving Routing Headers 
This example assumes that the application has enabled IPV6_ RECVRTHDR 


socket option. The application prints and reverses a source route 
and uses that to echo the received data. 
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struct sockaddr in6 addr; 
struct msghdr msg; 

struct iovec iov; 

struct cmsghdr *cmsgptr; 
socklen t cmsgspace; 
void *extptr; 
int extlen; 

int segments; 
int 13 

char databuf [8192]; 
segments = 100; /* Enough */ 


extlen = inet6 rth space(IPV6 RTHDR TYPE 0, segments); 
cmsgspace = CMSG SPACE (extlen) ; 
cmsgptr = malloc(cmsgspace) ; 


if (cmsgptr == NULL) { 
perror("malloc"); 
exit (1); 


} 
extptr = CMSG_DATA(cmsgptr) ; 


msg.msg_control = cmsgptr; 
msg.msg_controllen = cmsgspace; 
msg.msg_name = (struct sockaddr *)&addr; 
msg.msg_namelen = sizeof (addr); 
msg.msg_iov = &iov; 
msg.msg_iovlen = 1; 
iov.iov base = databuf; 
iov.iov len = sizeof (databuf); 
msg.msg flags = 0; 
if (recvmsg(s, &msg, 0) == -1) { 
perror("recvmsg"); 
return; 
) 
if (msg.msg controllen != 0 && 
cmsgptr->cmsg level == IPPROTO IPV6 && 
cmsgptr->cmsg type == IPV6 RTHDR) { 


struct in6 addr *in6; 
char asciiname [INET6_ADDRSTRLEN] ; 
struct ip6_rthdr *rthdr; 


rthdr = (struct ip6 rthdr *)extptr; 

segments = inet6_rth_segments (extptr) ; 

printf ("route (%d segments, %d left): ", 
segments, rthdr->ip6r segleft); 

for (i = 0; i < segments; i++) { 


in6 = inet6_rth_getaddr(extptr, i); 
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22. 


22. 


if (in6 == NULL) 
printf("<NULL> "); 
else 
printf("%s ", inet ntop(AF INET6, 
(void *)in6->s6 addr, 
asciiname, INET6 ADDRSTRLEN)); 
) 
if (inet6 rth reverse(extptr, extptr) == -1) { 
printf("reverse failed"); 
return; 


} 
} 


iov.iov base = databuf; 


iov.iov len = strlen(databuf); 

if (sendmsg(s, &msg, 0) == -1) 
perror("sendmsg"); 

if (cmsgptr != NULL) 


free(cmsgptr); 


Note: The above example is a simple illustration. It skips some 
error checks, including those involving the MSG TRUNC and MSG CTRUNC 
flags. It also leaves some type mismatches in favor of brevity. 


Appendix C: Examples Using the inet6 opt XXX() Functions 


This shows how Hop-by-Hop and Destination options can be both built 
as well as parsed using the inet6_opt_XXX() functions. These 
examples assume that there are defined values for OPT_X and OPT_Y. 


Note: The example is a simple illustration. It skips some error 
checks and leaves some type mismatches in favor of brevity. 


1. Building Options 


We now provide an example that builds two Hop-by-Hop options using 
the example in Appendix B of [RFC-2460]. 


void *extbuf; 
socklen_t extlen; 
int currentlen; 
void *databuf; 
int offset; 
uint8_t valuel; 
uintl6 t value2; 
uint32 t value4; 
uint64 t value8; 


/* Estimate the length */ 
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currentlen = inet6 opt init (NULL, 0); 
if (currentlen == -1) 
return (-1); 
currentlen = inet6_opt_append(NULL, 0, currentlen, OPT_X, 
12, 8, NULL); 


if (currentlen == -1) 
return (-1); 
currentlen = inet6_opt_append(NULL, 0, currentlen, OPT_Y, 
7, 4, NULL); 
if (currentlen == -1) 
return (-1); 
currentlen = inet6_opt_finish(NULL, 0, currentlen); 
if (currentlen == -1) 
return (-1); 
extlen = currentlen; 
extbuf = malloc(extlen); 
if (extbuf == NULL) { 
perror ("malloc"); 
return (-1); 
} 
currentlen = inet6_opt_init (extbuf, extlen); 
if (currentlen == -1) 
return (-1); 
currentlen = inet6_opt_append(extbuf, extlen, currentlen, 
OPT_X, 12, 8, &databuf); 
if (currentlen == -1) 
return (-1); 
/* Insert value 0x12345678 for 4-octet field */ 
offset = 0; 


value4 = 0x12345678; 
offset = inet6_opt_set_val(databuf, offset, 

&évalue4, sizeof (value4)); 
/* Insert value 0x0102030405060708 for 8-octet field */ 
value8 = 0x0102030405060708; 
offset = inet6_opt_set_val(databuf, offset, 

&value8, sizeof (value8)); 


currentlen = inet6 opt append(extbuf, extlen, currentlen, 
OPT Y, 7, 4, &databuf); 
if (currentlen == -1) 
return (-1); 
/* Insert value 0x01 for l-octet field */ 
offset = 0; 


valuel = 0x01; 
offset = inet6_opt_set_val(databuf, offset, 
&valuel, sizeof (valuel)); 
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/* Insert value 0x1331 for 2-octet field */ 
Value2 = 0x1331; 
offset = inet6 opt set val(databuf, offset, 

&value2, sizeof (value2)); 
/* Insert value 0x01020304 for 4-octet field */ 
Value4 = 0x01020304; 


offset = inet6 opt set val(databuf, offset, 

&value4, sizeof (value4)); 
currentlen = inet6_opt_finish(extbuf, extlen, currentlen); 
if (currentlen == -1) 


return (-1); 
/* extbuf and extlen are now completely formatted */ 


22.2. Parsing Received Options 


This example parses and prints the content of the two options in the 
previous example. 


int 
print_opt (void *extbuf, socklen_t extlen) 
{ 
struct ip6_dest *ext; 
int currentlen; 
uint8_t type; 
socklen_t len; 
void *databuf; 
int offset; 
uint8_t valuel; 
uintl6 t value2; 
uint32 t value4; 
uint64 t value8; 


ext = (struct ip6 dest *)extbuf; 
printf("nxt Su, len %u (bytes %d)\n", ext->ip6d nxt, 
ext->ip6d len, (ext->ipé6d len + 1) * 8); 


currentlen = 0; 
while (1) ( 
currentlen = inet6 opt next (extbuf, extlen, 
currentlen, &type, 
&len, &databuf); 
if (currentlen == -1) 
break; 
printf("Received opt %u len %u\n", 
type, len); 


switch (type) { 
case OPT_X: 
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offset = 0; 
offset = 
inet6 opt get val(databuf, offset, 
&valuedf, 
sizeof (value4)); 
printf("X 4-byte field %x\n", value4); 
offset = 
inet6 opt get val(databuf, offset, 
&value8, 
sizeof (value8)); 
printf("X 8-byte field %11x\n", value8); 
break; 
case OPT_Y: 
offset = 0; 
offset = 
inet6_opt_get_val(databuf, offset, 
&valuel, 
sizeof (valuel)); 
printf("Y 1-byte field %x\n", valuel); 
offset = 
inet6 opt get val(databuf, offset, 
&value2, 
sizeof (value2)); 
printf("Y 2-byte field %x\n", value2); 
offset = 
inet6 opt get val(databuf, offset, 
&évalue4, 
sizeof (value4)); 
printf("Y 4-byte field %x\n", value4); 


break; 

default: 
printf("Unknown option %u\n", type); 
break; 


} 
} 


return (0); 
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